332 lines
19 KiB
Markdown
332 lines
19 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.
|
||
|
||
**Milestone 2 — dependable daily CLI: complete.** Phase 3 passed its acceptance
|
||
gates on 2026-09-20. The Phase 4 format contract was approved on 2026-09-20.
|
||
|
||
**Milestone 3 — safe format transition: superseded before release.** Its
|
||
prototype migration proved the transaction design, then was deliberately
|
||
removed when the reversible layout became the only initial format.
|
||
|
||
**Milestone 4 — Git-like reversible workflow: complete.** Phase 4 passed its
|
||
default and portable test, Clippy, and release gates on 2026-09-21. Format 1.0
|
||
is native, transactional, staged, immutable, and recoverable.
|
||
|
||
**Milestone 5 — first TUI checkpoint: complete.** Its read-only scope,
|
||
terminal lifecycle, keyboard contract, and accessibility gate passed default
|
||
and portable release gates on 2026-09-21. See
|
||
[`docs/tui-design.md`](docs/tui-design.md).
|
||
|
||
**Milestone 6 — pre-release format consolidation: complete.** Native
|
||
initialisation now creates the reversible format directly; the unreleased
|
||
prototype reader, migration command, fixtures, and compatibility aliases are
|
||
removed. Future evolution uses explicit `1.x` major/minor versions. Default
|
||
and portable quality and release gates passed on 2026-09-21.
|
||
|
||
**Milestone 7 — deterministic worldgen foundation: complete.** The spatial,
|
||
fuzzing, configuration, rendering, and release-asset contract is approved in
|
||
[`docs/simulation-worldgen-design.md`](docs/simulation-worldgen-design.md).
|
||
Embedded and override configuration, deterministic generation, safe CLI apply,
|
||
packaging, and default/portable release gates passed on 2026-09-21.
|
||
|
||
**Example checkpoint — curated Draän base world: complete.** A clean,
|
||
committed repository with a copied 3840×2160 map, 50 positioned entities, lore,
|
||
governance links, and active events is tracked under
|
||
[`examples/ravenous-draan`](examples/ravenous-draan/README.md). Integration
|
||
tests open it as a real repository and validate its map and world invariants.
|
||
|
||
**History semantics checkpoint: complete.** `revert` now defaults to a
|
||
reviewable worktree inverse, `revert --commit` warns before adding history, and
|
||
`reset --hard` provides a previewed, explicitly confirmed destructive rewind.
|
||
Recoverable future pruning remains the recommended alternative and rewinds the
|
||
next epoch to `HEAD + 1`, with allocator and tags included in its backup.
|
||
|
||
**Tracker checkpoint — inspection and audit: complete.** Gitea issues #18 and
|
||
#19 are addressed by unified filtered entity/epoch inspection, and #14 now
|
||
validates links in every historical epoch. The remaining tracker items are
|
||
mapped to implemented, partial, blocked, and planned work in
|
||
[`docs/issue-audit.md`](docs/issue-audit.md).
|
||
|
||
**Tracker checkpoint — stat domains: complete.** Issue #15 now has one
|
||
enforced policy across CLI edits, TUI drafts, derived-stat recalculation, and
|
||
workspace validation without clamping real population counts.
|
||
|
||
## 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.
|
||
- [x] 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.
|
||
- [x] Ensure entity editing validates type-specific fields and reports useful
|
||
recovery advice.
|
||
- [x] 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
|
||
|
||
- [x] Approve the written design for working state, pseudo-staging, committed
|
||
epochs, and recovery semantics before implementing it. See
|
||
[the Phase 4 proposal](docs/staging-design.md).
|
||
- [x] Define `diff`, `stage`, `unstage`/`restore --staged`, `commit`, `restore`,
|
||
`revert`, and `log` behavior, including entity-level selection.
|
||
- [x] Define crash consistency, locking, concurrent-process behavior, and
|
||
repository format versioning.
|
||
- [x] Retire the pre-release migration fixture matrix once its source format
|
||
was confirmed never to have shipped.
|
||
- [x] Make `efo init` create HEAD, index, worktree, and format-1.0 manifest
|
||
transactionally without a migration step.
|
||
- [x] Add durable single-file transaction journaling, exclusive writer locks,
|
||
lock inspection/break primitives, and deterministic interrupted-write
|
||
recovery.
|
||
- [x] Extend transactions across ordered multi-file commits with rollback
|
||
copies and a manifest-last commit point.
|
||
- [x] Remove the obsolete migration rollback surface and retain transaction
|
||
recovery for interrupted writes.
|
||
- [x] Implement worktree/index-aware `status`, `diff`, `stage`, and both restore
|
||
directions without changing immutable epochs.
|
||
- [x] Implement committed epochs, `log`, reviewable and conflict-safe `revert`,
|
||
backed-up `prune-future`, and explicit previewed `reset --hard` destruction.
|
||
- [x] Complete Phase 4 only after every ordinary mistake is reversible without
|
||
manual JSON editing and both default and portable release gates pass.
|
||
|
||
## 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.
|
||
|
||
## TUI checkpoint 1 — safe repository browser
|
||
|
||
- [x] Approve the separate-binary architecture and read-only first-pass scope.
|
||
- [x] Define keyboard navigation, compact-layout, accessibility, and terminal
|
||
restoration requirements.
|
||
- [x] Add the `efo-tui` workspace binary without coupling `lib_efo` to a
|
||
terminal framework.
|
||
- [x] Render HEAD/index/worktree status and all entity collections.
|
||
- [x] Provide collection, entity, and detail navigation with contextual help.
|
||
- [x] Report unsupported, corrupt, locked, and interrupted repositories with the
|
||
next useful CLI command.
|
||
- [x] Unit test state transitions and deterministic rendering with a test
|
||
backend.
|
||
- [x] Document installation, startup, keys, scope, and CLI fallback paths.
|
||
- [x] Pass default and portable formatting, test, strict Clippy, and release
|
||
gates without running release-only badge tooling.
|
||
|
||
## Simulation and generation track
|
||
|
||
### Checkpoint 1 — deterministic configuration-driven worldgen
|
||
|
||
- [x] Define cumulative event/settlement/region/world generation levels.
|
||
- [x] Choose embedded defaults plus explicit local `--config` overrides.
|
||
- [x] Define seeded reproducibility, preview/apply behavior, and restoration.
|
||
- [x] Add a versioned `WorldGenConfig` with strict semantic validation.
|
||
- [x] Move canonical defaults to `lib_efo/assets/worldgen/default.json` and
|
||
embed them in the library.
|
||
- [x] Generate deterministic IDs, positions, names, events, and entity counts
|
||
from a caller-supplied seed without thread-local randomness.
|
||
- [x] Add `efo gen world --level ... --seed ... [--config ...] [--apply]` with
|
||
preview as the default and worktree-only application.
|
||
- [x] Add seed-replay, invalid-config, invariant, and CLI reversal tests.
|
||
- [x] Package the editable config and schema notes as a reproducible zip;
|
||
document the Gitea release upload endpoint without publishing in routine CI.
|
||
|
||
### Checkpoint 2 — roads, residency, and travel
|
||
|
||
- [ ] Add stable, validated road edges between positioned place entities.
|
||
- [ ] Model resident, roaming, and travelling character states without
|
||
overloading governance links.
|
||
- [ ] Implement deterministic shortest-time routing with road speed and slower
|
||
direct-travel fallback.
|
||
- [ ] Preview travel plans and advance progress only through staged simulation
|
||
ticks with clear restore/revert guidance.
|
||
- [ ] Fuzz disconnected, cyclic, duplicate, and malformed topology.
|
||
|
||
### Checkpoint 3 — spatial event diffusion
|
||
|
||
- [ ] Define event origins, speed, frontier, affected-set, and expiry data.
|
||
- [ ] Diffuse over roads and slower direct distance using configured
|
||
coefficients and deterministic tie-breaking.
|
||
- [ ] Preview each tick with route/reason output before applying it.
|
||
- [ ] Test repeated application, convergence, expiry, disconnected graphs, and
|
||
deterministic replay across many seeds.
|
||
|
||
### Checkpoint 4 — PNG map rendering
|
||
|
||
- [ ] Store optional base-map path and coordinate bounds without embedding
|
||
image bytes in repository history.
|
||
- [ ] Render entities, roads, travellers, events, and diffusion fronts onto a
|
||
supplied PNG or a generated blank RGBA canvas.
|
||
- [ ] Use shape and labels as well as colour, enforce allocation limits, and
|
||
atomically write a distinct output path.
|
||
- [ ] Add pixel/snapshot fixtures for blank and supplied-base rendering.
|
||
- [ ] Add `efo map render` help, examples, and recovery-safe error messages.
|
||
|
||
## Stretch goals — proposal only
|
||
|
||
These require user approval and are not part of the current implementation:
|
||
|
||
- [x] Previewed TUI entity creation/editing and one-step undo through library
|
||
transactions (authorized in the entity-authoring request below).
|
||
- [ ] 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.
|
||
- The former ignored `epoch switch --force` placeholder was removed; there is
|
||
no uncommitted/staged state for it to discard in the current format.
|
||
- Nerd Font rendering remains the default; portable text/Unicode rendering is
|
||
available through `--no-default-features` and passes its own test matrix.
|
||
- 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 eleven integration tests covering every exposed entity type,
|
||
timeline workflows, invalid input, and corrupted repositories.
|
||
- Phase 4 adds worktree/index state, entity and world staging, explicit restore,
|
||
manifest-last commits, parent-linked log/revert/switch, backed-up pruning,
|
||
writer locks, journals, and deterministic recovery.
|
||
- The binary integration workflows and format-1.0 library coverage
|
||
includes clean/dirty layers, commits, conflict refusal, time advancement,
|
||
include lock exclusion and interrupted-journal refusal.
|
||
- The separate read-only `efo-tui` binary browses status and all entity
|
||
collections with semantic labels, guarded terminal restoration, reload,
|
||
contextual help, compact-layout fallback, and three focused unit tests.
|
||
- After pre-release format consolidation, all 88 default-feature tests, 84
|
||
portable-output tests, strict Clippy, and both release builds passed on
|
||
2026-09-21.
|
||
- The worldgen foundation raised coverage to 93 default-feature tests and 89
|
||
portable-output tests; strict Clippy and both release builds still pass.
|
||
- Local source material under `ressources/` is ignored; the curated Draän
|
||
example remains tracked and carries a warning about its provisional reserved
|
||
setting/map rights.
|
||
- The milestone-only `rust_autobadges` run was attempted, but this installed
|
||
version misreported passing tests as failing and coverage as unavailable.
|
||
Its false generated badges were discarded; the prior badges were preserved.
|
||
- [x] Add focused `EpochInfo` collection, lookup, link, replacement, and
|
||
position tests; document and provide a runnable `lib_efo` repository example.
|
||
- [x] Configure Tarpaulin around its subprocess-attribution limitation and
|
||
refresh `rust_autobadges` at a directly measured coverage level above 70%.
|
||
|
||
## TUI release-readiness pass
|
||
|
||
- [x] Add searchable, sorted entity lists and HEAD/index/worktree browsing.
|
||
- [x] Improve detail rendering, bounded scrolling, paging, and compact layouts.
|
||
- [x] Preserve selection on reload and expose full reload diagnostics.
|
||
- [x] Harden terminal lifecycle, Ctrl-C, non-terminal startup, and no-colour output.
|
||
- [x] Add rendering, navigation, failure, and binary workflow coverage; update docs.
|
||
- Decision: this pass matures the read-only browser; interactive writes retain
|
||
the preview/recovery design requirements in `docs/tui-design.md`.
|
||
|
||
- Fixed multiline JSON details, stale reload selection, help clipping, blank
|
||
overscroll, and list-window jumps when navigating upward.
|
||
- The browser uses Ratatui's locked rendered-line measurement feature for exact
|
||
wrapped scroll bounds. Persisted repository data is unchanged.
|
||
- Validation: 109 all-feature tests and 105 portable tests, formatting, strict
|
||
Clippy, both release builds, and Unix PTY navigation/resize/restoration checks.
|
||
TUI coverage includes nine state/render tests and three binary startup tests.
|
||
- Release boundary: write workflows and history comparison stay in the CLI;
|
||
cross-terminal visual review remains useful before publishing a final release.
|
||
|
||
## TUI formatted details
|
||
|
||
- [x] Default entity/event details to a readable, sectioned presentation.
|
||
- [x] Toggle formatted/raw JSON with `v`, preserving selection and resetting scroll.
|
||
- [x] Cover modal keys and both representations; update help and docs and run gates.
|
||
- Decision: format serialized fields in the TUI so nested/future metadata stays
|
||
visible without changing domain types or persistence.
|
||
- Validation: 112 all-feature tests and 108 portable tests, formatting, strict
|
||
Clippy, both release builds, and the PTY smoke check passed.
|
||
|
||
## TUI entity authoring
|
||
|
||
- [x] Add forms for all six entity collections, validation, save previews, and draft cancellation.
|
||
- [x] Save only the worktree through library transactions with locked stale-state checks.
|
||
- [x] Add previewed one-step undo preserving the exact prior entity, including unstaged edits.
|
||
- [x] Cover creation/edit/undo, lock/conflict/failure paths, modal input and terminal workflows.
|
||
- [x] Update browser-only scope and help; pass quality gates and commit.
|
||
- Decision: this request authorizes TUI entity writes. HEAD/index remain read-only;
|
||
staging, commits, relationship editing, and general deletion remain CLI operations.
|
||
- Save checks hold the writer lock from fresh-state validation through the
|
||
journalled worktree write. Undo retains its own save-time snapshot so reload
|
||
cannot accidentally permit overwriting later edits. Entity order is preserved.
|
||
- Forms edit name, description, exact position, duration, effect, bounds, and
|
||
absolute statistics; relationship metadata and UUID/type remain intact.
|
||
- Undo is one step and session-local. Commit valuable work for durable recovery;
|
||
an index restore is intentionally documented as discarding all unstaged edits.
|
||
- Validation: 120 all-feature tests, 116 portable tests, formatting, strict
|
||
Clippy, default/portable release builds, and Unix PTY create/edit/preview/undo/
|
||
discard/multiline-paste/terminal-restoration checks passed.
|