diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md new file mode 100644 index 0000000..073af85 --- /dev/null +++ b/AGENTS-TASKS.md @@ -0,0 +1,118 @@ +# 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 + +- [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`. +- [ ] 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; classify all 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 generated from 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 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. +- 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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bfed774 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# Epoch Forge contributor guide + +Epoch Forge is a CLI-first, local world-state manager. Its primary product +qualities are, in order: safety and reversibility, ease of use, compatibility +with existing repositories, and pleasant terminal output. Do not add a GUI, +web service, or TUI unless a task explicitly changes that scope. + +## Product vocabulary + +- A **repository** is a directory initialised by `efo init`. +- An **epoch** is an immutable-in-spirit snapshot of world state. Commands may + edit the checked-out epoch, but every destructive workflow must have a clear + recovery path. +- An **entity** is a typed game object such as a character, town, event, + blocker, calamity, or (eventually) organisation. +- An **identifier** may be a human-readable name or the stable `@UUID` form. +- The CLI is `efo`; `lib_efo` owns the domain and persistence logic while + `bin_efo` owns argument parsing and presentation. + +## Engineering rules + +1. Preserve persisted data compatibility. If a format change is unavoidable, + add a version/migration plan and fixtures before changing it. +2. Mutating commands must either complete fully or leave the prior on-disk + state usable. Prefer write-to-temporary-then-rename where practical. +3. Destructive commands require an explicit, documented recovery path. Model + vocabulary after Git where it helps: `status`, `log`, `diff`, `switch`, + `restore`, and later `stage`/`commit`. +4. Errors must say what failed, identify the relevant object/path, and suggest + the next useful command when one exists. Do not panic for user input or + repository corruption. +5. `efo --help` and every subcommand's `--help` are user documentation. Include + meaningful summaries, argument value hints, and examples where Clap allows. +6. Human output should be compact, aligned, Unicode-aware, and colour only when + appropriate for the terminal. Machine-readable output must remain plain and + stable. Never require a Nerd Font to understand essential output. +7. Keep domain operations in `lib_efo`; CLI handlers should parse, invoke, and + render. Avoid `unsafe`, unchecked `unwrap`, and hidden working-directory + mutations. +8. Custom organisation/entity fields are a planned compatibility direction. + Avoid closed designs that prevent adding schema-less metadata later. + +## Quality gates + +Run before each implementation commit: + +```text +cargo fmt --all -- --check +cargo test --workspace --all-targets --all-features --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +``` + +Add tests at the lowest useful layer and CLI integration tests for observable +workflows. Tests that touch a repository must use a temporary directory and +must not depend on execution order. Snapshot tests are appropriate for stable +human output; assertions on structured data are preferred for persistence. + +Tarpaulin and `rust_autobadges` are release-time tools. Do not run them in CI or +for routine commits. Refresh their badges only for a significant release. + +## Documentation and commits + +- Keep the README short: purpose, honest capability summary, quick start, + safety model, and links into `docs/`. +- Keep commands, repository format, architecture, and roadmap in focused, + cross-linked files under `docs/`. +- Update documentation in the same commit as user-visible behavior. +- Maintain `AGENTS-TASKS.md`: mark completed items, add discoveries, and record + decisions that affect later work. +- Commit small coherent changes regularly. Use conventional subjects such as + `docs:`, `test:`, `fix:`, `feat:`, and `refactor:`. Never mix an unrelated + cleanup with a behavior change. + +## Definition of done + +A task is done when behavior is implemented, failure modes are covered, the +full quality gates pass, CLI help and relevant docs agree with reality, and the +change is committed with `AGENTS-TASKS.md` updated.