epoch_forge/AGENTS-TASKS.md

7.5 KiB
Raw Blame History

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 --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.
  • 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 show path.
  • 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

  • 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, and log behavior, 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 Monster naming, 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 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.
  • All 73 default-feature tests, 69 portable-output tests, strict Clippy, and both release builds passed on 2026-09-20.
  • 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.