23 KiB
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.
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.
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. 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.
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
and docs/presentation-design.md.
Phase 0 — audit and guardrails
- Inventory workspace crates, commands, persistence files, CI, and tests.
- Run the untouched baseline test suite (58 library tests; 0 binary tests).
- Record product and engineering conventions in
AGENTS.md. - Capture baseline
--helpoutput and exercise a complete temporary-repo workflow; record every command that panics, lies, or mutates unexpectedly. - Run formatting and strict Clippy; remove all baseline warnings.
- Map the current
.epochconfig/ epoch-directory format and its recovery properties before changing persistence.
Phase 1 — honest documentation and CLI contract
- Replace the README's advertised-but-missing commands with a concise, verified capability summary and working quick start.
- Add
docs/README.mdas the documentation index. - Add a command reference based on verified
--helpbehavior. - Document the repository layout, identifiers, epochs, persistence, and manual backup/recovery procedure.
- Add an architecture guide covering crate boundaries and data flow.
- Add a compatibility policy for stored data and CLI scripts.
- Add a roadmap that distinguishes implemented, current-release, planned, and stretch work.
- Correct typos, stale rustdoc examples, and misleading comments.
Phase 2 — test and harden the existing product
- Add CLI integration-test infrastructure using the built
efobinary and isolated temporary directories. - Test root and nested help, version output, invalid commands, and exit status/stderr conventions.
- Test
init, including non-empty directories, already initialised repos, and the promised--forcesemantics. - Test
statusand repository discovery/error reporting. - Test the full entity lifecycle for each exposed type: add, show, edit, diff, and delete by name and stable identifier.
- Test epoch workflows: next, log, switch, diff, tag, summary, and reset.
- Test malformed/corrupt configuration and snapshot files without panics.
- Test interrupted/failed writes where feasible and implement atomic file replacement for repository metadata and epoch snapshots.
- Remove currently reported unused dependencies and the demo
showpath. - Make format, tests, strict Clippy, and release build pass.
Phase 3 — finish the intended current CLI
- Make
efo showinspect actual world state or replace it with a coherent command surface; remove its current generated demonstration output. - Make
efo statusclearly show current epoch, timeline divergence/future snapshots, entity totals, and a clean/modified indicator if detectable. - Implement and test truthful
epoch diffoutput. - Implement
epoch fsckwith read-only checks for config, directories, parent links, tags, IDs, entity references, and parseability. - Make
init --forcesafe and explicit; it must not silently destroy an existing Epoch Forge repository or unrelated files. - 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.
- 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
- Approve the written design for working state, pseudo-staging, committed epochs, and recovery semantics before implementing it. See the Phase 4 proposal.
- Define
diff,stage,unstage/restore --staged,commit,restore,revert, andlogbehavior, including entity-level selection. - Define crash consistency, locking, concurrent-process behavior, and repository format versioning.
- Retire the pre-release migration fixture matrix once its source format was confirmed never to have shipped.
- Make
efo initcreate HEAD, index, worktree, and format-1.0 manifest transactionally without a migration step. - Add durable single-file transaction journaling, exclusive writer locks, lock inspection/break primitives, and deterministic interrupted-write recovery.
- Extend transactions across ordered multi-file commits with rollback copies and a manifest-last commit point.
- Remove the obsolete migration rollback surface and retain transaction recovery for interrupted writes.
- Implement worktree/index-aware
status,diff,stage, and both restore directions without changing immutable epochs. - Implement committed epochs,
log, reviewable and conflict-saferevert, backed-upprune-future, and explicit previewedreset --harddestruction. - 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
- Approve the separate-binary architecture and read-only first-pass scope.
- Define keyboard navigation, compact-layout, accessibility, and terminal restoration requirements.
- Add the
efo-tuiworkspace binary without couplinglib_efoto a terminal framework. - Render HEAD/index/worktree status and all entity collections.
- Provide collection, entity, and detail navigation with contextual help.
- Report unsupported, corrupt, locked, and interrupted repositories with the next useful CLI command.
- Unit test state transitions and deterministic rendering with a test backend.
- Document installation, startup, keys, scope, and CLI fallback paths.
- 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
- Define cumulative event/settlement/region/world generation levels.
- Choose embedded defaults plus explicit local
--configoverrides. - Define seeded reproducibility, preview/apply behavior, and restoration.
- Add a versioned
WorldGenConfigwith strict semantic validation. - Move canonical defaults to
lib_efo/assets/worldgen/default.jsonand embed them in the library. - Generate deterministic IDs, positions, names, events, and entity counts from a caller-supplied seed without thread-local randomness.
- Add
efo gen world --level ... --seed ... [--config ...] [--apply]with preview as the default and worktree-only application. - Add seed-replay, invalid-config, invariant, and CLI reversal tests.
- 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.
- Exercise disconnected, cyclic, duplicate, malformed, and legacy topology in deterministic tests; broader cargo-fuzz targets remain release hardening.
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 3.5 — tracker simulation resolution (#9, #8, #12)
- Approve the shared prework contract in
docs/resolution-conflict-design.md. - Add a separately versioned, embedded
AdjudicationConfigwith strict validation, external replacement, safety limits, and release packaging. - 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.
- Implement all six stable master-assigned levels, explicit effects, disposition-controlled attenuation, clamping, and stale-checkable reports.
- Persist idempotent, stale-state-checked adjudication records with workspace
and historical
fsckvalidation. - Add preview/apply/list
adjudicatecommands plus the familiarinfluxalias and complete help examples. Records deliberately cannot be cleared independently of their effects; use worktree restore or historical revert. - Make explicit effects optional: embedded/configurable defaults use a
monotonic excellent-to-apocalypse dampening scale, while any
--effectreplaces the fallback and the audit record identifies which path was used. - 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.
- Resolve diffusion arrivals against protected towns and configured blockers, explaining avoided/dampened/destroyed outcomes.
- 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.
- 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)
- Approve the remaining renderer/export contract in
docs/presentation-design.mdand 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 renderhelp, examples, and recovery-safe error messages.
Stretch goals — proposal only
These require user approval and are not part of the current implementation:
- 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
-
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). -
Add ephemeral UUID/name
EntityIndexlookup and duplicate detection while preserving ordered vectors as the stable repository representation (#6). -
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
showoutput, ignoredinit --force, and panickingepoch diff/epoch fsckpaths were replaced and covered by CLI tests. -
The former ignored
epoch switch --forceplaceholder 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-featuresand passes its own test matrix. -
Name generation used to create
naming.jsonin 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-tuibinary 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_autobadgesrun 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. -
Add focused
EpochInfocollection, lookup, link, replacement, and position tests; document and provide a runnablelib_eforepository example. -
Configure Tarpaulin around its subprocess-attribution limitation and refresh
rust_autobadgesat a directly measured coverage level above 70%.
TUI release-readiness pass
-
Add searchable, sorted entity lists and HEAD/index/worktree browsing.
-
Improve detail rendering, bounded scrolling, paging, and compact layouts.
-
Preserve selection on reload and expose full reload diagnostics.
-
Harden terminal lifecycle, Ctrl-C, non-terminal startup, and no-colour output.
-
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
- Default entity/event details to a readable, sectioned presentation.
- Toggle formatted/raw JSON with
v, preserving selection and resetting scroll. - 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
- Add forms for all six entity collections, validation, save previews, and draft cancellation.
- Save only the worktree through library transactions with locked stale-state checks.
- Add previewed one-step undo preserving the exact prior entity, including unstaged edits.
- Cover creation/edit/undo, lock/conflict/failure paths, modal input and terminal workflows.
- 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.