docs: establish project guardrails and delivery plan
This commit is contained in:
parent
e9cf45ca7a
commit
d9b656f74c
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue