# Write Metadata Round 5 Plan

## Summary

Round 5 should strengthen write provenance before adding more UI or caching. The main goal is to enrich lifecycle writes with explicit metadata and thread that contract through service, CLI, GUI, and MCP.

The work is sequenced in this order:

1. extend ledger entries with transition metadata
2. expose metadata fields through service write APIs
3. expose metadata through CLI and MCP write tools
4. verify backward compatibility and update handoff status

## Key Changes

### Ledger / domain

- add optional transition metadata fields:
  - `actor`
  - `reason`
  - `evidence_refs`
- preserve append-only behavior
- preserve compatibility with older ledger entries that do not contain metadata

### Surface updates

- CLI write commands accept metadata flags
- MCP write tools accept metadata arguments
- GUI may keep metadata entry deferred unless a minimal UX fits cleanly

## Test Plan

- backward-compatible ledger read tests
- write tests with and without metadata
- CLI tests for metadata flags
- MCP tests for metadata arguments

## Assumptions

- Round 5 does not add persistent projection cache
- Round 5 does not redesign the GUI workbench
- Round 5 keeps the existing MCP tool names stable

## Completion Status

Last checked: `2026-04-12`

Completed in this round:

- added optional event-level write metadata:
  - `actor`
  - `reason`
  - `evidence_refs`
- preserved backward-compatible ledger deserialization for old entries without metadata
- threaded metadata through `LifecycleStore`, `LifecycleService`, CLI write commands, and MCP write tools
- exposed metadata in CLI output, MCP structured responses, and GUI detail rendering
- verification completed with full test and check passes

Checked for omissions against this plan:

- no missed items inside the scoped implementation baseline
- persistent projection cache remains intentionally deferred
- GUI creation/edit UX remains intentionally deferred
- MCP tool names remain stable
