epoch_forge/AGENTS-TASKS.md

6.7 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.

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 --help output 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.md as the documentation index.
  • Add a command reference based on verified --help behavior.
  • 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 efo binary 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 --force semantics.
  • Test status and repository discovery/error reporting. (Happy-path status is covered; repository discovery and error cases remain.)
  • 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 unused dependencies and dead/demo command paths.
  • Make format, tests, strict Clippy, and release build pass.

Phase 3 — finish the intended current CLI

  • Make efo show inspect actual world state or replace it with a coherent command surface; remove its current generated demonstration output.
  • Make efo status clearly show current epoch, timeline divergence/future snapshots, entity totals, and a clean/modified indicator if detectable.
  • Implement and test truthful epoch diff output.
  • Implement epoch fsck with read-only checks for config, directories, parent links, tags, IDs, entity references, and parseability.
  • Make init --force safe 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, and log behavior, 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 README currently describes organisation/link/event interfaces that are absent from the top-level parser.
  • show currently prints a randomly generated entity repeatedly and does not inspect repository data.
  • init exposes --force, but the handler does not use it.
  • epoch diff and epoch fsck panic through unimplemented!().
  • epoch switch --force is 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.json in the working directory; this was removed in favor of read-only embedded defaults.
  • The binary crate currently has no tests; most coverage is parsing/model-level.
  • Existing library tests passed on 2026-09-20. Tarpaulin was intentionally not run because badges are release-only by project policy.