6.8 KiB
6.8 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. Phase 3 is the next active milestone.
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
- 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, andlogbehavior, 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
showoutput, ignoredinit --force, and panickingepoch diff/epoch fsckpaths were replaced and covered by CLI tests. epoch switch --forceis 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.jsonin 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.