epoch_forge/AGENTS-TASKS.md

403 lines
23 KiB
Markdown
Raw Permalink 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.
**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.
**Milestone 3 — safe format transition: superseded before release.** Its
prototype migration proved the transaction design, then was deliberately
removed when the reversible layout became the only initial format.
**Milestone 4 — Git-like reversible workflow: complete.** Phase 4 passed its
default and portable test, Clippy, and release gates on 2026-09-21. Format 1.0
is native, transactional, staged, immutable, and recoverable.
**Milestone 5 — first TUI checkpoint: complete.** Its read-only scope,
terminal lifecycle, keyboard contract, and accessibility gate passed default
and portable release gates on 2026-09-21. See
[`docs/tui-design.md`](docs/tui-design.md).
**Milestone 6 — pre-release format consolidation: complete.** Native
initialisation now creates the reversible format directly; the unreleased
prototype reader, migration command, fixtures, and compatibility aliases are
removed. Future evolution uses explicit `1.x` major/minor versions. Default
and portable quality and release gates passed on 2026-09-21.
**Milestone 7 — deterministic worldgen foundation: complete.** The spatial,
fuzzing, configuration, rendering, and release-asset contract is approved in
[`docs/simulation-worldgen-design.md`](docs/simulation-worldgen-design.md).
Embedded and override configuration, deterministic generation, safe CLI apply,
packaging, and default/portable release gates passed on 2026-09-21.
**Example checkpoint — curated Draän base world: complete.** A clean,
committed repository with a copied 3840×2160 map, 50 positioned entities, lore,
governance links, and active events is tracked under
[`examples/ravenous-draan`](examples/ravenous-draan/README.md). Integration
tests open it as a real repository and validate its map and world invariants.
**History semantics checkpoint: complete.** `revert` now defaults to a
reviewable worktree inverse, `revert --commit` warns before adding history, and
`reset --hard` provides a previewed, explicitly confirmed destructive rewind.
Recoverable future pruning remains the recommended alternative and never
reuses removed epoch IDs; allocator and tags are included in its backup.
**Tracker checkpoint — inspection and audit: complete.** Gitea issues #18 and
#19 are addressed by unified filtered entity/epoch inspection, and #14 now
validates links in every historical epoch. The remaining tracker items are
mapped to implemented, partial, blocked, and planned work in
[`docs/issue-audit.md`](docs/issue-audit.md).
**Tracker checkpoint — stat domains: complete.** Issue #15 now has one
enforced policy across CLI edits, TUI drafts, derived-stat recalculation, and
workspace validation without clamping real population counts.
**Tracker prework — issues #9, #8, #10, and #12: complete.** The shared
deterministic resolution, diffusion-outcome, generic conflict, presentation,
export, persistence, CLI, safety, and test contracts are implementation-ready
in [`docs/resolution-conflict-design.md`](docs/resolution-conflict-design.md)
and [`docs/presentation-design.md`](docs/presentation-design.md).
## 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.
- [x] 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.
- [x] Ensure entity editing validates type-specific fields and reports useful
recovery advice.
- [x] 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
- [x] Approve the written design for working state, pseudo-staging, committed
epochs, and recovery semantics before implementing it. See
[the Phase 4 proposal](docs/staging-design.md).
- [x] Define `diff`, `stage`, `unstage`/`restore --staged`, `commit`, `restore`,
`revert`, and `log` behavior, including entity-level selection.
- [x] Define crash consistency, locking, concurrent-process behavior, and
repository format versioning.
- [x] Retire the pre-release migration fixture matrix once its source format
was confirmed never to have shipped.
- [x] Make `efo init` create HEAD, index, worktree, and format-1.0 manifest
transactionally without a migration step.
- [x] Add durable single-file transaction journaling, exclusive writer locks,
lock inspection/break primitives, and deterministic interrupted-write
recovery.
- [x] Extend transactions across ordered multi-file commits with rollback
copies and a manifest-last commit point.
- [x] Remove the obsolete migration rollback surface and retain transaction
recovery for interrupted writes.
- [x] Implement worktree/index-aware `status`, `diff`, `stage`, and both restore
directions without changing immutable epochs.
- [x] Implement committed epochs, `log`, reviewable and conflict-safe `revert`,
backed-up `prune-future`, and explicit previewed `reset --hard` destruction.
- [x] Complete Phase 4 only after every ordinary mistake is reversible without
manual JSON editing and both default and portable release gates pass.
## 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.
## TUI checkpoint 1 — safe repository browser
- [x] Approve the separate-binary architecture and read-only first-pass scope.
- [x] Define keyboard navigation, compact-layout, accessibility, and terminal
restoration requirements.
- [x] Add the `efo-tui` workspace binary without coupling `lib_efo` to a
terminal framework.
- [x] Render HEAD/index/worktree status and all entity collections.
- [x] Provide collection, entity, and detail navigation with contextual help.
- [x] Report unsupported, corrupt, locked, and interrupted repositories with the
next useful CLI command.
- [x] Unit test state transitions and deterministic rendering with a test
backend.
- [x] Document installation, startup, keys, scope, and CLI fallback paths.
- [x] Pass default and portable formatting, test, strict Clippy, and release
gates without running release-only badge tooling.
## Simulation and generation track
### Checkpoint 1 — deterministic configuration-driven worldgen
- [x] Define cumulative event/settlement/region/world generation levels.
- [x] Choose embedded defaults plus explicit local `--config` overrides.
- [x] Define seeded reproducibility, preview/apply behavior, and restoration.
- [x] Add a versioned `WorldGenConfig` with strict semantic validation.
- [x] Move canonical defaults to `lib_efo/assets/worldgen/default.json` and
embed them in the library.
- [x] Generate deterministic IDs, positions, names, events, and entity counts
from a caller-supplied seed without thread-local randomness.
- [x] Add `efo gen world --level ... --seed ... [--config ...] [--apply]` with
preview as the default and worktree-only application.
- [x] Add seed-replay, invalid-config, invariant, and CLI reversal tests.
- [x] Package the editable config and schema notes as a reproducible zip;
document the Gitea release upload endpoint without publishing in routine CI.
### Checkpoint 2 — roads, residency, and travel
- [x] Add stable, validated road edges between positioned place entities.
- [x] Model resident, roaming, and travelling character states without
overloading governance links.
- [x] Implement deterministic shortest-time routing with road speed and slower
direct-travel fallback.
- [x] Preview travel plans and advance progress only through staged simulation
ticks with clear restore/revert guidance.
- [x] Exercise disconnected, cyclic, duplicate, malformed, and legacy topology
in deterministic tests; broader cargo-fuzz targets remain release hardening.
### Checkpoint 3 — spatial event diffusion
- [x] Define event origins, speed, frontier, affected-set, and expiry data.
- [x] Diffuse over roads and slower direct distance using configured
coefficients and deterministic tie-breaking.
- [x] Preview each tick with route/reason output before applying it.
- [x] Test repeated application, convergence, expiry, disconnected graphs, and
deterministic replay across many seeds.
### Checkpoint 3.5 — tracker simulation resolution (#9, #8, #12)
- [x] Approve the shared prework contract in
`docs/resolution-conflict-design.md`.
- [x] Add a separately versioned, embedded `AdjudicationConfig` with strict
validation, external replacement, safety limits, and release packaging.
- [x] Correct the original influx assumption: an adjudication records a
player-made external roll plus the master's level, disposition, explanation,
and explicit effects; Epoch Forge never rolls or invents an effect.
- [x] Implement all six stable master-assigned levels, explicit effects,
disposition-controlled attenuation, clamping, and stale-checkable reports.
- [x] Persist idempotent, stale-state-checked adjudication records with workspace
and historical `fsck` validation.
- [x] Add preview/apply/list `adjudicate` commands plus the familiar `influx`
alias and complete help examples. Records deliberately cannot be cleared
independently of their effects; use worktree restore or historical revert.
- [x] Make explicit effects optional: embedded/configurable defaults use a
monotonic excellent-to-apocalypse dampening scale, while any `--effect`
replaces the fallback and the audit record identifies which path was used.
- [x] Persist source-event potency outside ordinary statistics, monotonically
dampen future policy-default effects, expose it in command output, and make a
destroyed ruling expire/prevent diffusion with restore/revert recovery.
- [x] Resolve diffusion arrivals against protected towns and configured
blockers, explaining avoided/dampened/destroyed outcomes.
- [x] Resolve resident and positioned characters deterministically; document
the initial policy for characters currently in transit.
- [x] Add generic multi-side conflict records, participant validation, pure
fight/war round resolution, victory, stalemate, and explicit ending.
- [x] Add conflict commands and focused fight/war aliases with preview-first,
worktree-only application and restore/stage/commit/revert coverage.
- [ ] Cover every adjudication level/disposition, corruption, allocation limits,
multi-side conflict, and diffusion/conflict integration.
- [x] Cover deterministic preview, explicit effects, attenuation, avoided and
destroyed no-op effects, clamping, stale/repeated application, CLI audit,
aliasing, and worktree restoration.
### Presentation completion (#10)
- [x] Approve the remaining renderer/export contract in
`docs/presentation-design.md` and inventory production direct output.
- [ ] Add shared output options, semantic document blocks, a single process
sink, and an atomic non-overwriting output-file writer.
- [ ] Migrate destructive/safety and simulation previews to typed reports and
buffered human/plain/JSON rendering.
- [ ] Migrate state/history, entity, and generation output without changing
domain behavior.
- [ ] Remove production printing from `lib_efo`; retain strings or writer-based
compatibility APIs only where necessary.
- [ ] Add a source-policy check preventing new production print macros outside
the output sink and entry error boundary.
- [ ] Test colour/portable/redirection behavior, stable JSON schemas, output
collisions, permission failures, atomicity, large lists, and help examples.
- Raw audit baseline: 122 print-macro call sites across 15 source files;
comments and test-only calls will be excluded when enforcing the final gate.
### Checkpoint 4 — PNG map rendering
- [ ] Store optional base-map path and coordinate bounds without embedding
image bytes in repository history.
- [ ] Render entities, roads, travellers, events, and diffusion fronts onto a
supplied PNG or a generated blank RGBA canvas.
- [ ] Use shape and labels as well as colour, enforce allocation limits, and
atomically write a distinct output path.
- [ ] Add pixel/snapshot fixtures for blank and supplied-base rendering.
- [ ] Add `efo map render` help, examples, and recovery-safe error messages.
## Stretch goals — proposal only
These require user approval and are not part of the current implementation:
- [x] Previewed TUI entity creation/editing and one-step undo through library
transactions (authorized in the entity-authoring request below).
- [ ] 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
- [x] Replace duplicated epoch/layer comparison code with a deterministic,
serializable `WorldDiff`, changed-field details, importance marks, and a
buffered CLI renderer (tracker issues #11 and part of #10).
- [x] Add ephemeral UUID/name `EntityIndex` lookup and duplicate detection while
preserving ordered vectors as the stable repository representation (#6).
- [x] Make full entity, unified show, epoch show, and diff presentation return
buffered strings before the CLI writes them (tracker issue #10).
- [ ] Tracker issue #13 is intentionally deferred at the maintainer's request.
- 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.
- Phase 4 adds worktree/index state, entity and world staging, explicit restore,
manifest-last commits, parent-linked log/revert/switch, backed-up pruning,
writer locks, journals, and deterministic recovery.
- The binary integration workflows and format-1.0 library coverage
includes clean/dirty layers, commits, conflict refusal, time advancement,
include lock exclusion and interrupted-journal refusal.
- The separate read-only `efo-tui` binary browses status and all entity
collections with semantic labels, guarded terminal restoration, reload,
contextual help, compact-layout fallback, and three focused unit tests.
- After pre-release format consolidation, all 88 default-feature tests, 84
portable-output tests, strict Clippy, and both release builds passed on
2026-09-21.
- The worldgen foundation raised coverage to 93 default-feature tests and 89
portable-output tests; strict Clippy and both release builds still pass.
- Local source material under `ressources/` is ignored; the curated Draän
example remains tracked and carries a warning about its provisional reserved
setting/map rights.
- 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.
- [x] Add focused `EpochInfo` collection, lookup, link, replacement, and
position tests; document and provide a runnable `lib_efo` repository example.
- [x] Configure Tarpaulin around its subprocess-attribution limitation and
refresh `rust_autobadges` at a directly measured coverage level above 70%.
## TUI release-readiness pass
- [x] Add searchable, sorted entity lists and HEAD/index/worktree browsing.
- [x] Improve detail rendering, bounded scrolling, paging, and compact layouts.
- [x] Preserve selection on reload and expose full reload diagnostics.
- [x] Harden terminal lifecycle, Ctrl-C, non-terminal startup, and no-colour output.
- [x] Add rendering, navigation, failure, and binary workflow coverage; update docs.
- Decision: this pass matures the read-only browser; interactive writes retain
the preview/recovery design requirements in `docs/tui-design.md`.
- Fixed multiline JSON details, stale reload selection, help clipping, blank
overscroll, and list-window jumps when navigating upward.
- The browser uses Ratatui's locked rendered-line measurement feature for exact
wrapped scroll bounds. Persisted repository data is unchanged.
- Validation: 109 all-feature tests and 105 portable tests, formatting, strict
Clippy, both release builds, and Unix PTY navigation/resize/restoration checks.
TUI coverage includes nine state/render tests and three binary startup tests.
- Release boundary: write workflows and history comparison stay in the CLI;
cross-terminal visual review remains useful before publishing a final release.
## TUI formatted details
- [x] Default entity/event details to a readable, sectioned presentation.
- [x] Toggle formatted/raw JSON with `v`, preserving selection and resetting scroll.
- [x] Cover modal keys and both representations; update help and docs and run gates.
- Decision: format serialized fields in the TUI so nested/future metadata stays
visible without changing domain types or persistence.
- Validation: 112 all-feature tests and 108 portable tests, formatting, strict
Clippy, both release builds, and the PTY smoke check passed.
## TUI entity authoring
- [x] Add forms for all six entity collections, validation, save previews, and draft cancellation.
- [x] Save only the worktree through library transactions with locked stale-state checks.
- [x] Add previewed one-step undo preserving the exact prior entity, including unstaged edits.
- [x] Cover creation/edit/undo, lock/conflict/failure paths, modal input and terminal workflows.
- [x] Update browser-only scope and help; pass quality gates and commit.
- Decision: this request authorizes TUI entity writes. HEAD/index remain read-only;
staging, commits, relationship editing, and general deletion remain CLI operations.
- Save checks hold the writer lock from fresh-state validation through the
journalled worktree write. Undo retains its own save-time snapshot so reload
cannot accidentally permit overwriting later edits. Entity order is preserved.
- Forms edit name, description, exact position, duration, effect, bounds, and
absolute statistics; relationship metadata and UUID/type remain intact.
- Undo is one step and session-local. Commit valuable work for durable recovery;
an index restore is intentionally documented as discarding all unstaged edits.
- Validation: 120 all-feature tests, 116 portable tests, formatting, strict
Clippy, default/portable release builds, and Unix PTY create/edit/preview/undo/
discard/multiline-paste/terminal-restoration checks passed.