7.5 KiB
7.5 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; implementation is now proceeding through isolated compatibility checkpoints.
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.
- Add a version-1 migration fixture matrix covering empty and populated
histories, tags, future epochs, relationships, legacy
Monsternaming, and malformed input; materialise each case through the real legacy manifest and snapshot types. - 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. - 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.
- All 73 default-feature tests, 69 portable-output tests, strict Clippy, and both release builds passed on 2026-09-20.
- 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.