# TODO

Status values: TODO / DOING / DONE / BLOCKED

| ID | Status | Module | Task | Files/Dirs | Done When | Validation | Static Analysis | ADR/C4 Update |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| T-000A | DONE | Architecture Gate | Clean up source-of-truth and V1 Alpha vocabulary | `AirPlan/docs/architecture/{baselineV1.md,main-agent-state-machine.md,*-v1.md}`, `AirPlan/plan.md` | MVP/V1.0.0 Alpha terminology is unambiguous; `packages/contracts` is in the canonical package list; Main Agent state machine is V1-aligned; C++ DiagnosticParser ownership matches runtime semantics | All architecture docs reviewed | No unresolved precedence conflicts | baseline, main-agent-state-machine, 13 *-v1.md files, plan, and solution-architecture updated |
| T-000B | DONE | Contracts Gate | Repair public contract freeze issues | `AirPlan/docs/architecture/interface-contracts-v1.md`, `event-registry-v1.md`, `error-taxonomy-v1.md`, `provider-capability-matrix-v1.md`, `tool-registry-v1.md`, `c4/code-view.md` | P0 contract conflicts resolved: `AirError.cause_ref`/`cause_refs`, `EntityRef` single-source, `permission_template` naming, `TaskInsert`/`EventInsert`, `TaskType/docs`, `Diagnostic`, `DebugKnowledgeStore`/`LearnedMemoryStore`, `PromptLayer`/`CompactionPolicy`, `ProviderAdapter` snake_case, `WaveID`, IPC handshake/direction, `EventSchemaRegistry`, `StreamingToolExecutor`, `PermissionRecordResult` | All contract edits verified | Contracts can be transcribed to `packages/contracts` without conflicts | C4 interface inventory updated implicitly via contract changes |
| T-000C | DONE | Runtime Gate | Define persistence and runtime invariants | `AirPlan/docs/architecture/db-schema-v1.md`, `runtime-semantics-v1.md`, `event-registry-v1.md`, `interface-contracts-v1.md` | `debug-records.db` and `learned-memory.db` DDL added; FK-off invariants defined; EventBus handler error behavior defined; PermissionEngine record failure path defined; DB closed enum inventory added; workspace GC policy defined; direct mode, ExperienceMiner triggers, Doctor self-bootstrap, air restore semantics defined | All runtime/runtime-semantics and db-schema edits verified | Storage/runtime docs cover invariants needed by EventStore, repositories, recovery, and permission audit | runtime-semantics sections 14-19 added; db-schema sections 20-21 added |
| T-000D | DONE | UX Scope Gate | Alpha UX scope decided | `AirPlan/plan.md`, `AirPlan/todo.md`, `AirPlan/docs/analysis/requirements.md`, `AirPlan/docs/architecture/main-agent-state-machine.md` | All UX features scheduled as Alpha tasks; VibeBox removed from main plan (separate project branch) | Requirements-to-todo trace check | No original UX requirement silently unscheduled | T-038 through T-045 created; VibeBox references removed from plan/todo |
| T-000E | DONE | Overview Gate | Repair system overview after four-model audit | `AirPlan/docs/architecture/system-overview-design.md`, `AirPlan/docs/architecture/{gpt5概要设计审查.md,mimo2.5概要设计审查.md,Opus4.7概要设计审查.md,DeepSeek概要设计审查.md,概要设计修复回归审查.md}`, `AirPlan/plan.md`, `AirPlan/AGENTS.md` | All P0/P1 and non-decision P2 overview audit gaps are folded into the overview; all 24 frozen baselines are listed; error taxonomy, global `~/.air`, IPC, TaskSpec/WorkerResult, PermissionEngine, RuntimeEvent, SQLite message invariants, state machines, capability trust, artifact naming, logging/migration/scanner/distribution/test strata are covered | Four-review consensus applied; regression review passed | No remaining overview blocker before detailed design | `system-overview-design.md` repaired; regression report, plan, and AGENTS synchronized |
| T-000F | DONE | Detailed Design Gate | Produce system detailed design and UML class diagrams | `AirPlan/docs/architecture/system-detailed-design.md` | 23 sections covering all packages, classes, methods, state machines, sequences, and traceability matrix; 8 Mermaid UML class diagrams; strict derivation from frozen baselines | Document structure matches contracts/code-view/state-machines/db-schema | All class signatures match frozen contracts; no new public contracts introduced | plan.md and AGENTS.md updated |
| T-001 | TODO | Monorepo | Create Bun workspace and Turborepo skeleton | `package.json`, `turbo.json`, `packages/` | Workspace installs and scripts resolve | `bun install && bun run typecheck` | TypeScript config validates package graph | ADR-0002, C4 package dependency view |
| T-002 | TODO | Contracts | Implement shared contract package | `packages/contracts/src/` | RuntimeEvent, TaskSpec, WorkerResult, ToolDefinition, ArtifactRef, EvidenceRef, provider, error, IPC, UI types compile | `bun test packages/contracts && bun run typecheck` | Type-only package has no implementation deps | C4 interface inventory |
| T-003 | TODO | CLI | Implement CLI bootstrap shell | `packages/cli/src/` | CLI can start, print version/help, locate project root, load resources | `bun run air -- --help` | Typecheck CLI package | C4 container view |
| T-004 | TODO | Project Store | Implement `.air` project initializer | `packages/runtime/src/project/` | Creates `.air/shared` and `.air/local` with project ID and default rules/config | `bun run air -- init <fixture>` | Typecheck runtime project module | ADR-0003 |
| T-005 | TODO | Storage | Implement SQLite schema V1 migration | `packages/runtime/src/storage/`, `.air/local/sessions/*/session.db` | New session DB matches `db-schema-v1.md` | `bun test packages/runtime --filter storage` | SQL migration checked by tests | ADR-0004 |
| T-006 | TODO | EventStore | Implement durable EventStore and event validation | `packages/runtime/src/events/` | Durable events validate, persist, and update domain tables transactionally | `bun test packages/runtime --filter eventstore` | Event payload types compile against registry | ADR-0004, event registry |
| T-007 | TODO | ArtifactStore | Implement artifact write/URI/hash/DB flow | `packages/runtime/src/artifacts/` | Artifacts write temp→rename, sha256 recorded, artifact.created emitted | `bun test packages/runtime --filter artifact` | Artifact metadata typecheck | artifact naming baseline |
| T-008 | TODO | Permission | Implement path classifier and PermissionEngine core | `packages/runtime/src/security/` | Project/system/credential/build/git paths classified by realpath; decisions recorded | `bun test packages/runtime --filter permission` | Security model types compile | ADR-0007, security model |
| T-009 | TODO | Permission | Implement command risk analyzer | `packages/runtime/src/security/commands.ts` | Shell commands classify read/build/destructive/system/credential risk | `bun test packages/runtime --filter command-risk` | Typecheck risk rules | security model |
| T-010 | TODO | Tools | Implement ToolRegistry core | `packages/runtime/src/tools/` | Tools register, schemas validate, lifecycle events emitted | `bun test packages/runtime --filter tool-registry` | ToolDefinition generics compile | ADR-0007, tool registry |
| T-011 | TODO | Tools | Implement filesystem tools | `packages/runtime/src/tools/fs/` | `fs.list/read/write/edit/patch/stat` follow read-before-edit and exact edit rules | `bun test packages/runtime --filter fs-tools` | Typecheck schemas | ADR-0006 |
| T-012 | TODO | Tools | Implement shell/process tools | `packages/runtime/src/tools/shell/` | `shell.run` captures command events/artifacts; `process.kill` permissioned | `bun test packages/runtime --filter shell-tools` | Typecheck schemas | security model |
| T-013 | TODO | Tools | Implement git tools | `packages/runtime/src/tools/git/` | status/diff/worktree/create/merge paths work on fixture repo | `bun test packages/runtime --filter git-tools` | Typecheck schemas | scheduler/workspace flow |
| T-014 | TODO | Tools | Implement project, artifact, context, permission, doctor tools | `packages/runtime/src/tools/{project,artifact,context,permission,doctor}/` | Core internal tools callable through ToolRegistry | `bun test packages/runtime --filter core-tools` | Typecheck schemas | tool registry |
| T-015 | TODO | Capability | Implement CapabilityRegistry and built-in manifests | `packages/runtime/src/capabilities/`, `resources/capabilities/` | Built-in capabilities load, validate, and register tools | `bun test packages/runtime --filter capability` | Manifest schema validation | capability trust model |
| T-016 | TODO | LLM | Implement provider config and capability matrix loader | `packages/llm/src/` | Global/project model config loads and validates capabilities | `bun test packages/llm --filter capability` | Typecheck provider matrix | ADR-0008 |
| T-017 | TODO | LLM | Implement one provider adapter path | `packages/llm/src/providers/` | At least one Anthropic-compatible or OpenAI-compatible call path works under config | `bun run air -- provider smoke` | Adapter output types validate | provider matrix |
| T-018 | TODO | Context | Implement ContextAssembler L0-L9 | `packages/runtime/src/context/`, `resources/prompts/` | Assembles Anthropic canonical context with omissions/conflict reporting | `bun test packages/runtime --filter context` | Prompt asset schema checks | prompt layering model |
| T-019 | TODO | IPC | Implement NDJSON IPC framing | `packages/runtime/src/ipc/` | Parent/child can exchange event/control/log messages | `bun test packages/runtime --filter ipc` | IPC message types compile | ADR-0005 |
| T-020 | TODO | Workers | Implement worker process bootstrap skeletons | `packages/runtime/src/workers/` | Executor/Reviewer/Debugger/Compactor/ExperienceMiner start and return stub WorkerResult | `bun run air -- e2e worker-fixture` | WorkerResult schema validation | C4 worker view |
| T-021 | TODO | Scheduler | Implement TaskGraph loading and wave planning | `packages/runtime/src/scheduler/` | Scheduler loads tasks/deps and plans runnable wave with write-area serialization | `bun test packages/runtime --filter scheduler-graph` | Typecheck SchedulerWavePlan | scheduler state machine |
| T-022 | TODO | Scheduler | Implement dispatch, heartbeat, timeout, retry, and recovery | `packages/runtime/src/scheduler/` | Child workers dispatch, heartbeat monitored, lost workers recovered, retry budget enforced | `bun test packages/runtime --filter scheduler-runtime` | Error taxonomy mapping checked | scheduler state machine |
| T-023 | TODO | Scheduler | Implement workspace merge flow | `packages/runtime/src/scheduler/workspace.ts` | Worktree workspace created, merged, conflict event emitted on conflict | `bun test packages/runtime --filter workspace` | Typecheck workspace events | ADR-0005, C4 merge sequence |
| T-024 | TODO | Toolchain C++ | Implement C++ detection/configure/build/test tools | `packages/toolchain-cpp/src/` | Fixture C++ project detects, configures, builds, and tests | `bun run air -- fixture cpp-build-test` | Typecheck toolchain schemas | C++ baseline |
| T-025 | TODO | Toolchain C++ | Implement cppcheck/clangd/diagnostic parsing | `packages/toolchain-cpp/src/analysis/` | Static analysis and clangd query produce diagnostics with semantic signatures | `bun test packages/toolchain-cpp` | cppcheck on fixture if available | C++ baseline |
| T-026 | TODO | Projection | Implement ProjectionStore | `packages/runtime/src/projection/` | Hydrates from DB and applies live events for session/task/agent/tool views | `bun test packages/runtime --filter projection` | Projection types compile | ADR-0004 |
| T-027 | TODO | TUI | Implement OpenTUI/Solid startup and core views | `packages/tui/src/` | TUI starts and shows session/task/agent/tool projections | `bun run air -- tui-smoke --project <fixture>` | Typecheck TUI package | C4 TUI container |
| T-028 | TODO | TUI | Implement permission/blocker/report UI surfaces | `packages/tui/src/` | Permission prompts and blocker reports render from ProjectionStore | `bun test packages/tui` | Typecheck UI contracts | scope escalation/security model |
| T-029 | TODO | Agents | Implement Main Agent request classification shell | `packages/runtime/src/agents/main/` | Main Agent stores messages, classifies direct vs delegated work, and reports progress | `bun test packages/runtime --filter main-agent` | Prompt schema checks | solution architecture |
| T-030 | TODO | Agents | Implement Architecture Designer impact and review gate flow | `packages/runtime/src/agents/architecture/` | Requirement/interface changes produce architecture impact events and doc update tasks; architecture-sensitive reviews, phase-complete reviews, and final consistency reviews produce Architecture Designer gate results | `bun test packages/runtime --filter architecture-agent` | Structured output validation | scope escalation ADRs, system overview §10.5 |
| T-031 | TODO | Agents | Implement Executor/Reviewer/Debugger minimal loops | `packages/runtime/src/workers/roles/` | Simple edit fixture can execute, review, debug failure, and return evidence | `bun run air -- e2e simple-edit-fixture` | WorkerResult schema checks | ADR-0006 |
| T-032 | TODO | Compaction | Implement Compactor summary flow | `packages/runtime/src/workers/roles/compactor.ts` | Context budget pressure creates summary row/artifact and preserves backtracking refs | `bun test packages/runtime --filter compaction` | Summary schema validation | prompt layering/context baseline |
| T-033 | TODO | Experience | Implement ExperienceMiner candidate flow with Nudge, Curator, and self-patch | `packages/runtime/src/workers/roles/experience-miner.ts`, `packages/runtime/src/workers/roles/curator.ts` | Verified pattern creates memory/rule candidate; N-turn Nudge trigger fires periodically; Curator dedup/archive runs; self-patch forwards stale rules to ExperienceMiner | `bun test packages/runtime --filter experience` | Candidate/Curator/self-patch schema validation | memory baseline, runtime-semantics §17 |
| T-034 | TODO | Doctor | Implement Doctor with read-only, fix mode, and bundle export | `packages/runtime/src/doctor/` | Platform, provider config, toolchain, display, disk, permissions checks report; fix mode applies fixes under PermissionEngine; bundle exports diagnostic archive | `bun run air -- doctor --read-only && bun run air -- doctor --fix --dry-run && bun run air -- doctor --bundle` | Doctor report/bundle schema validation | security/platform matrix, runtime-semantics §19 |
| T-035 | TODO | Logging | Implement user/developer logs | `packages/runtime/src/logging/` | `air.log` user errors and encrypted developer log path exist with retention policy hooks | `bun test packages/runtime --filter logging` | Secret redaction tests | security/logging baseline |
| T-036 | TODO | E2E | Implement release gate fixtures | `fixtures/`, `scripts/release-check.*` | Worker, C++ build/test, DB recovery, TUI startup, artifact/event persistence gates, phase-complete architecture review, and final Architecture Designer consistency review run | `bun run release:check` | Typecheck/lint/test all packages | cross-platform matrix, scope escalation |
| T-037 | TODO | Packaging | Implement binary tarball packaging | `scripts/package.*`, `resources/` | Tarball contains `bin/air`, `resources/`, `LICENSE` and starts on tier-1 Linux | `bun run release:package` | Package smoke validation | distribution baseline |
| T-038 | TODO | Main Agent | Implement `/direct` and `/done` direct mode | `packages/runtime/src/agents/main/`, `packages/tui/src/` | Main Agent enters DIRECT_MODE with executor permissions; `/done` exits and collects evidence; direct mode events logged | `bun run air -- e2e direct-mode-fixture` | Direct mode state machine and permission template checks | main-agent-state-machine, runtime-semantics §16 |
| T-039 | TODO | CLI | Implement `air restore` with three granularities | `packages/cli/src/commands/restore.ts`, `packages/runtime/src/restore/` | `air restore file`, `air restore time`, `air restore session` work from git-backed backup repo | `bun test packages/runtime --filter restore` | Restore schema and git operation validation | decisions-round-2 D-032, runtime-semantics §20 |
| T-040 | TODO | CLI | Implement CLI command catalog | `packages/cli/src/commands/` | `air resume`, `air compact`, `air history`, `air session list`, and read-only `air provider list/current` commands exist and function; no runtime provider/model switching command exists | `bun run air -- help` shows full catalog; individual commands have `--help` | Command typecheck and help output validation | requirements FR-005, baseline §18 |
| T-041 | TODO | Main Agent | Implement `compact` and `resume` user commands | `packages/runtime/src/agents/main/`, `packages/cli/src/commands/` | `air compact` triggers manual compaction; `air resume` restores session from DB | `bun run air -- e2e compact-resume-fixture` | Compaction and resume schema validation | runtime-semantics §7, prompt-layering |
| T-042 | TODO | Main Agent | Implement `history` and `session list` commands | `packages/cli/src/commands/` | `air history` shows session message history; `air session list` lists sessions with status | `bun run air -- session list` and `bun run air -- history` | Output format and DB query validation | db-schema, projection |
| T-043 | TODO | TUI | Implement permission prompt UX with announce_then_run visualization | `packages/tui/src/components/PermissionPrompt.tsx` | Permission prompts render risk level, options, and announce_then_run mode; user decisions flow through UiCommandChannel | `bun test packages/tui --filter permission` | Permission prompt UI snapshot validation | security-model, scope-escalation |
| T-044 | TODO | TUI | Implement evidence display in TUI | `packages/tui/src/components/EvidenceView.tsx` | Users can expand/view artifact previews, log tails, screenshots inline from evidence refs | `bun test packages/tui --filter evidence` | Evidence view rendering validation | artifact-naming, interface-contracts §14 |
| T-045 | TODO | TUI | Implement HUD presets (Full/Essential/Minimal) | `packages/tui/src/components/HudView.tsx`, `packages/tui/src/theme/` | HUD renders in Full/Essential/Minimal presets; user can switch | `bun run air -- tui-smoke --project <fixture>` | HUD preset rendering validation | requirements FR-016 |

## Quality Gates

- T-000A through T-000E are DONE. System overview design is repaired after four-model audit; detailed design and `packages/contracts` implementation may proceed.
- Run the validation command listed for the task before marking it `DONE`.
- Keep ADR and C4 docs synchronized whenever architecture, module boundaries, dependencies, or ownership change.
- Record skipped validation, residual risk, and follow-up work explicitly.
- Do not mark code-changing tasks done without artifact/evidence references where applicable.
- All side-effect tools must pass PermissionEngine tests before worker E2E tasks rely on them.
