epoch_forge/AGENTS-TASKS.md

127 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
- [x] Run the untouched baseline test suite (58 library tests; 0 binary tests).
- [x] Record product and engineering conventions in `AGENTS.md`.
- [x] Capture baseline `--help` output and exercise a complete temporary-repo
workflow; record every command that panics, lies, or mutates unexpectedly.
- [x] Run formatting and strict Clippy; remove all baseline warnings.
- [x] Map the current `.epochconfig` / epoch-directory format and its recovery
properties before changing persistence.
## Phase 1 — honest documentation and CLI contract
- [x] Replace the README's advertised-but-missing commands with a concise,
verified capability summary and working quick start.
- [x] Add `docs/README.md` as the documentation index.
- [x] Add a command reference based on verified `--help` behavior.
- [x] Document the repository layout, identifiers, epochs, persistence, and
manual backup/recovery procedure.
- [x] Add an architecture guide covering crate boundaries and data flow.
- [x] Add a compatibility policy for stored data and CLI scripts.
- [x] Add a roadmap that distinguishes implemented, current-release, planned,
and stretch work.
- [x] Correct typos, stale rustdoc examples, and misleading comments.
## Phase 2 — test and harden the existing product
- [x] Add CLI integration-test infrastructure using the built `efo` binary and
isolated temporary directories.
- [x] Test root and nested help, version output, invalid commands, and exit
status/stderr conventions.
- [x] Test `init`, including non-empty directories, already initialised repos,
and the promised `--force` semantics.
- [x] Test `status` and repository discovery/error reporting.
- [x] Test the full entity lifecycle for each exposed type: add, show, edit,
diff, and delete by name and stable identifier.
- [x] Test epoch workflows: next, log, switch, diff, tag, summary, and reset.
- [x] Test malformed/corrupt configuration and snapshot files without panics.
- [x] Test interrupted/failed writes where feasible and implement atomic file
replacement for repository metadata and epoch snapshots.
- [x] Remove currently reported unused dependencies and the demo `show` path.
- [x] Make format, tests, strict Clippy, and release build pass.
## Phase 3 — finish the intended current CLI
- [x] Make `efo show` inspect actual world state or replace it with a coherent
command surface; remove its current generated demonstration output.
- [x] Make `efo status` clearly show current epoch, timeline divergence/future
snapshots, entity totals, and a clean/modified indicator if detectable.
- [x] Implement and test truthful `epoch diff` output.
- [x] Implement `epoch fsck` with read-only checks for config, directories,
parent links, tags, IDs, entity references, and parseability.
- [x] Make `init --force` safe and explicit; it must not silently destroy an
existing Epoch Forge repository or unrelated files.
- [x] 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.
- [x] 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 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.
- `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 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.