docs: establish project guardrails and delivery plan

This commit is contained in:
Dandaedre 2026-09-20 20:47:41 +02:00
parent e9cf45ca7a
commit d9b656f74c
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
2 changed files with 196 additions and 0 deletions

118
AGENTS-TASKS.md Normal file
View File

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

78
AGENTS.md Normal file
View File

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