---
id: document-cross-table-status-mapping
name: Document Cross-Table Status Enum Disambiguation
status: completed
depends_on: []
scope: moderate
risk: medium
impact: phase
level: implementation
---

## Description

W11: Three tables have `status` with overlapping values (`completed`, `failed`, `aborted` appear on `mappings`, `call_graph_nodes`, and `tasks`), but the meanings differ (e.g., `mappings.completed` ≠ `tasks.completed`). `table-reference.md` only contrasts `mappings.active` vs `call_graph_nodes.pending/running` — it doesn't contrast `tasks` statuses with the others.

Add cross-table state mapping documentation. When a task goes `in-progress`, there should be an active mapping; when a task is `completed`, the mapping becomes `completed`. Document valid combinations and the semantic differences between same-named statuses in different tables.

## Acceptance Criteria

- [ ] `table-reference.md` has a cross-table status mapping section (table or diagram)
- [ ] Each shared status value (`completed`, `failed`, `aborted`) has per-table semantic definition
- [ ] Valid cross-table status combinations documented (e.g., task `in-progress` ⟹ mapping `active`)
- [ ] `tasks.status` lifecycle contrasted with `mappings.status` lifecycle
- [ ] Note that `mappings.completed` and `tasks.completed` have different semantic scope

## References

- docs/reviews/storage-architecture-review-2026-04-21.md#W11
- docs/architecture/storage/table-reference.md:147-164
- docs/architecture/storage/coordination.md:23
- docs/architecture/storage/tasks.md:84-86

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion