# Lifecycle Implementation Plan

## Summary

This plan defines the current implementation baseline for moving `spool` from a read-only memory lifecycle prototype into an operable lifecycle workbench.

The work is sequenced in this order:

1. add a shared lifecycle service for GUI / CLI reuse
2. add minimum GUI action flow for review items
3. add CLI lifecycle read/write commands
4. verify against this plan and update handoff docs with completed items

## Key Changes

### Shared lifecycle service

- add a service layer above `LifecycleStore`
- expose workbench reads:
  - pending review
  - wakeup-ready
  - record lookup by `record_id`
- expose write actions:
  - `Accept`
  - `PromoteToCanonical`
  - `Archive`
- keep append-only ledger behavior unchanged
- keep invalid transitions as hard failures with no dirty append

### GUI minimum action flow

- replace the read-only lifecycle text areas with:
  - selectable pending review list
  - selectable wakeup-ready list
  - record detail view
  - action buttons for the selected record
- action visibility rules:
  - `Candidate`: `Accept`, `Archive`
  - `Accepted`: `Promote`, `Archive`
  - `Canonical`: `Archive`
- refresh lifecycle panels after every successful action
- keep the GUI intentionally narrow:
  - no batch actions
  - no inline edit
  - no event history browser
  - no manual memory creation form

### CLI lifecycle surface

- add `memory` subcommands alongside existing `get`, `explain`, `wakeup`
- first-stage commands:
  - `memory list`
  - `memory show`
  - `memory accept`
  - `memory promote`
  - `memory archive`
- all CLI lifecycle commands must reuse the shared lifecycle service

## Test Plan

- service tests:
  - load workbench snapshot
  - accept candidate
  - promote accepted memory
  - archive wakeup-ready memory
  - reject invalid transitions without append
- GUI tests:
  - selected record exposes the correct actions
  - lifecycle state refreshes after successful action
  - failed action preserves useful status/error output
- CLI tests:
  - list pending review
  - show record details
  - accept / promote / archive commands succeed
  - invalid actions fail with readable errors

## Assumptions

- this phase does not add MCP tooling yet
- this phase does not change `memory-ledger.jsonl` schema
- this phase does not add `actor`, `reason`, or `evidence_refs`
- this phase does not add persistent projection cache

## Completion Status

Last checked: `2026-04-11`

Completed in this phase:

- shared lifecycle service added for GUI / CLI reuse
- GUI upgraded from read-only lifecycle text panes to selectable review lists with detail + actions
- CLI gained `memory list`, `memory show`, `memory accept`, `memory promote`, `memory archive`
- verification completed with full test and check passes

Checked for omissions against this plan:

- no missed items inside the scoped implementation baseline
- MCP tooling remains intentionally deferred
- ledger schema changes remain intentionally deferred
- audit metadata (`actor`, `reason`, `evidence_refs`) remains intentionally deferred
- persistent projection caching remains intentionally deferred
