# 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 never reuses removed epoch IDs; allocator and tags are 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. **Tracker prework — issues #9, #8, #10, and #12: complete.** The shared deterministic resolution, diffusion-outcome, generic conflict, presentation, export, persistence, CLI, safety, and test contracts are implementation-ready in [`docs/resolution-conflict-design.md`](docs/resolution-conflict-design.md) and [`docs/presentation-design.md`](docs/presentation-design.md). ## 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 - [x] Add stable, validated road edges between positioned place entities. - [x] Model resident, roaming, and travelling character states without overloading governance links. - [x] Implement deterministic shortest-time routing with road speed and slower direct-travel fallback. - [x] Preview travel plans and advance progress only through staged simulation ticks with clear restore/revert guidance. - [x] Exercise disconnected, cyclic, duplicate, malformed, and legacy topology in deterministic tests; broader cargo-fuzz targets remain release hardening. ### Checkpoint 3 — spatial event diffusion - [x] Define event origins, speed, frontier, affected-set, and expiry data. - [x] Diffuse over roads and slower direct distance using configured coefficients and deterministic tie-breaking. - [x] Preview each tick with route/reason output before applying it. - [x] Test repeated application, convergence, expiry, disconnected graphs, and deterministic replay across many seeds. ### Checkpoint 3.5 — tracker simulation resolution (#9, #8, #12) - [x] Approve the shared prework contract in `docs/resolution-conflict-design.md`. - [x] Add a separately versioned, embedded `AdjudicationConfig` with strict validation, external replacement, safety limits, and release packaging. - [x] Correct the original influx assumption: an adjudication records a player-made external roll plus the master's level, disposition, explanation, and explicit effects; Epoch Forge never rolls or invents an effect. - [x] Implement all six stable master-assigned levels, explicit effects, disposition-controlled attenuation, clamping, and stale-checkable reports. - [x] Persist idempotent, stale-state-checked adjudication records with workspace and historical `fsck` validation. - [x] Add preview/apply/list `adjudicate` commands plus the familiar `influx` alias and complete help examples. Records deliberately cannot be cleared independently of their effects; use worktree restore or historical revert. - [x] Make explicit effects optional: embedded/configurable defaults use a monotonic excellent-to-apocalypse dampening scale, while any `--effect` replaces the fallback and the audit record identifies which path was used. - [x] Persist source-event potency outside ordinary statistics, monotonically dampen future policy-default effects, expose it in command output, and make a destroyed ruling expire/prevent diffusion with restore/revert recovery. - [x] Resolve diffusion arrivals against protected towns and configured blockers, explaining avoided/dampened/destroyed outcomes. - [x] Resolve resident and positioned characters deterministically; document the initial policy for characters currently in transit. - [ ] Add generic multi-side conflict records, participant validation, pure fight/war round resolution, victory, stalemate, and explicit ending. - [ ] Add conflict commands and focused fight/war aliases with preview-first, worktree-only application and restore/stage/commit/revert coverage. - [ ] Cover every adjudication level/disposition, corruption, allocation limits, multi-side conflict, and diffusion/conflict integration. - [x] Cover deterministic preview, explicit effects, attenuation, avoided and destroyed no-op effects, clamping, stale/repeated application, CLI audit, aliasing, and worktree restoration. ### Presentation completion (#10) - [x] Approve the remaining renderer/export contract in `docs/presentation-design.md` and inventory production direct output. - [ ] Add shared output options, semantic document blocks, a single process sink, and an atomic non-overwriting output-file writer. - [ ] Migrate destructive/safety and simulation previews to typed reports and buffered human/plain/JSON rendering. - [ ] Migrate state/history, entity, and generation output without changing domain behavior. - [ ] Remove production printing from `lib_efo`; retain strings or writer-based compatibility APIs only where necessary. - [ ] Add a source-policy check preventing new production print macros outside the output sink and entry error boundary. - [ ] Test colour/portable/redirection behavior, stable JSON schemas, output collisions, permission failures, atomicity, large lists, and help examples. - Raw audit baseline: 122 print-macro call sites across 15 source files; comments and test-only calls will be excluded when enforcing the final gate. ### 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 - [x] Replace duplicated epoch/layer comparison code with a deterministic, serializable `WorldDiff`, changed-field details, importance marks, and a buffered CLI renderer (tracker issues #11 and part of #10). - [x] Add ephemeral UUID/name `EntityIndex` lookup and duplicate detection while preserving ordered vectors as the stable repository representation (#6). - [x] Make full entity, unified show, epoch show, and diff presentation return buffered strings before the CLI writes them (tracker issue #10). - [ ] Tracker issue #13 is intentionally deferred at the maintainer's request. - 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.