---
id: improve-mappings-spec
name: Improve Mappings Spec — Project Scoping and Status Lifecycle
status: completed
depends_on: []
scope: narrow
risk: trivial
impact: isolated
level: implementation
---

## Description

Two improvements to the `mappings` table specification in `coordination.md`:

1. **S13**: Finding all active mappings for a project's tasks requires a JOIN through `sessions.projectId` or `tasks.projectId`. Either add a denormalized `projectId` column for direct project-scoped queries, or document that the JOIN pattern is acceptable and intentional.

2. **S14**: Unlike `tasks.status` which has an explicit lifecycle diagram, `mappings.status` transitions are unspecified. Add a lifecycle diagram or state machine showing valid transitions (e.g., `active → completed | failed | aborted`).

## Acceptance Criteria

- [ ] Either `projectId` column added to mappings table spec, or JOIN pattern documented as intentional
- [ ] `mappings.status` lifecycle diagram added to `coordination.md` with valid transitions
- [ ] `table-reference.md` updated if schema changes

## References

- docs/reviews/storage-architecture-review-2026-04-21.md#S13
- docs/reviews/storage-architecture-review-2026-04-21.md#S14
- docs/architecture/storage/coordination.md

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion