127 lines
6.8 KiB
Markdown
127 lines
6.8 KiB
Markdown
# Epoch Forge delivery plan
|
||
|
||
This is the working backlog for bringing the current CLI to a trustworthy
|
||
early-alpha release. Checkboxes describe completion, not intention. Newly found
|
||
work belongs here before implementation.
|
||
|
||
**Milestone 1 — trustworthy foundation: complete.** Phases 0–2 passed their
|
||
acceptance gates on 2026-09-20. Phase 3 is the next active milestone.
|
||
|
||
## Phase 0 — audit and guardrails
|
||
|
||
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
|
||
- [x] Run the untouched baseline test suite (58 library tests; 0 binary tests).
|
||
- [x] Record product and engineering conventions in `AGENTS.md`.
|
||
- [x] Capture baseline `--help` output and exercise a complete temporary-repo
|
||
workflow; record every command that panics, lies, or mutates unexpectedly.
|
||
- [x] Run formatting and strict Clippy; remove all baseline warnings.
|
||
- [x] Map the current `.epochconfig` / epoch-directory format and its recovery
|
||
properties before changing persistence.
|
||
|
||
## Phase 1 — honest documentation and CLI contract
|
||
|
||
- [x] Replace the README's advertised-but-missing commands with a concise,
|
||
verified capability summary and working quick start.
|
||
- [x] Add `docs/README.md` as the documentation index.
|
||
- [x] Add a command reference based on verified `--help` behavior.
|
||
- [x] Document the repository layout, identifiers, epochs, persistence, and
|
||
manual backup/recovery procedure.
|
||
- [x] Add an architecture guide covering crate boundaries and data flow.
|
||
- [x] Add a compatibility policy for stored data and CLI scripts.
|
||
- [x] Add a roadmap that distinguishes implemented, current-release, planned,
|
||
and stretch work.
|
||
- [x] Correct typos, stale rustdoc examples, and misleading comments.
|
||
|
||
## Phase 2 — test and harden the existing product
|
||
|
||
- [x] Add CLI integration-test infrastructure using the built `efo` binary and
|
||
isolated temporary directories.
|
||
- [x] Test root and nested help, version output, invalid commands, and exit
|
||
status/stderr conventions.
|
||
- [x] Test `init`, including non-empty directories, already initialised repos,
|
||
and the promised `--force` semantics.
|
||
- [x] Test `status` and repository discovery/error reporting.
|
||
- [x] Test the full entity lifecycle for each exposed type: add, show, edit,
|
||
diff, and delete by name and stable identifier.
|
||
- [x] Test epoch workflows: next, log, switch, diff, tag, summary, and reset.
|
||
- [x] Test malformed/corrupt configuration and snapshot files without panics.
|
||
- [x] Test interrupted/failed writes where feasible and implement atomic file
|
||
replacement for repository metadata and epoch snapshots.
|
||
- [x] Remove currently reported unused dependencies and the demo `show` path.
|
||
- [x] Make format, tests, strict Clippy, and release build pass.
|
||
|
||
## Phase 3 — finish the intended current CLI
|
||
|
||
- [x] Make `efo show` inspect actual world state or replace it with a coherent
|
||
command surface; remove its current generated demonstration output.
|
||
- [x] Make `efo status` clearly show current epoch, timeline divergence/future
|
||
snapshots, entity totals, and a clean/modified indicator if detectable.
|
||
- [x] Implement and test truthful `epoch diff` output.
|
||
- [x] Implement `epoch fsck` with read-only checks for config, directories,
|
||
parent links, tags, IDs, entity references, and parseability.
|
||
- [x] Make `init --force` safe and explicit; it must not silently destroy an
|
||
existing Epoch Forge repository or unrelated files.
|
||
- [x] Resolve naming inconsistencies (`chr`, calamity mapped to monster,
|
||
missing organisation surface) with aliases/deprecation where compatibility
|
||
warrants it.
|
||
- [ ] Improve all command help with examples and valid-value guidance.
|
||
- [x] Replace ambiguous success output and Nerd-Font-only semantics with clear,
|
||
attractive Unicode output that degrades safely without colour.
|
||
- [ ] Ensure entity editing validates type-specific fields and reports useful
|
||
recovery advice.
|
||
- [ ] Ensure every existing mutation has a documented and tested reversal via
|
||
epoch switching/reset/restore or an explicit backup workflow.
|
||
|
||
## Phase 4 — Git-like reversible workflow
|
||
|
||
- [ ] Write and approve a design for working state, pseudo-staging, committed
|
||
epochs, and recovery semantics before implementing it.
|
||
- [ ] Define `diff`, `stage`, `unstage`/`restore --staged`, `commit`, `restore`,
|
||
`revert`, and `log` behavior, including entity-level selection.
|
||
- [ ] Define crash consistency, locking, concurrent-process behavior, and
|
||
repository format versioning.
|
||
- [ ] Add migration fixtures for all prior supported repository versions.
|
||
- [ ] Implement only after the design preserves current data and allows every
|
||
ordinary mistake to be reversed without manual JSON editing.
|
||
|
||
## Phase 5 — organisation-agnostic extensibility (upcoming release)
|
||
|
||
- [ ] Design custom fields with stable serialization and typed scalar/list/map
|
||
values; retain unknown fields across old/new binary round trips.
|
||
- [ ] Generalise faction/organisation concepts without baking in fantasy-game
|
||
assumptions.
|
||
- [ ] Define schemas/templates, optional validation, inheritance, and display
|
||
ordering for custom entity kinds.
|
||
- [ ] Provide import/export and migration tooling before changing defaults.
|
||
- [ ] Test repositories containing user-defined fields and entity kinds.
|
||
|
||
## Stretch goals — proposal only
|
||
|
||
These require user approval and are not part of the current implementation:
|
||
|
||
- [ ] Interactive TUI layered over the exact same library operations (no GUI).
|
||
- [ ] Branching timelines with named branches and merge/conflict workflows.
|
||
- [ ] Shell completions and man pages generated from the Clap command model.
|
||
- [ ] JSON/JSONL output modes and stable query/filter expressions for scripts.
|
||
- [ ] Template packs for different settings (empire, company, guild, nation).
|
||
- [ ] Repository hooks for validation or simulation before committing an epoch.
|
||
- [ ] Optional signed snapshots and append-only audit records.
|
||
- [ ] Deterministic seeded simulation and reproducible random generation.
|
||
- [ ] Plugin/scripting boundary after the storage compatibility contract settles.
|
||
|
||
## Audit notes
|
||
|
||
- The old README described organisation/link/event interfaces absent from the
|
||
parser; the rewritten docs now distinguish current and planned behavior.
|
||
- The old demo `show` output, ignored `init --force`, and panicking `epoch diff`
|
||
/ `epoch fsck` paths were replaced and covered by CLI tests.
|
||
- `epoch switch --force` is parsed but ignored.
|
||
- Entity rendering emits ANSI escapes when stdout is redirected and relies on
|
||
several optional Nerd Font glyphs for labels.
|
||
- Name generation used to create `naming.json` in the working directory; this
|
||
was removed in favor of read-only embedded defaults.
|
||
- The binary now has nine integration tests covering every exposed entity type,
|
||
timeline workflows, invalid input, and corrupted repositories.
|
||
- All 70 tests and the release build passed on 2026-09-20. Tarpaulin was intentionally not
|
||
run because badges are release-only by project policy.
|