epoch_forge/AGENTS-TASKS.md

23 KiB
Raw Blame History

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.

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

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 and docs/presentation-design.md.

Phase 0 — audit and guardrails

  • Inventory workspace crates, commands, persistence files, CI, and tests.
  • Run the untouched baseline test suite (58 library tests; 0 binary tests).
  • 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; remove all baseline 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 based on 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 currently reported unused dependencies and the demo show path.
  • 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

  • Approve the written design for working state, pseudo-staging, committed epochs, and recovery semantics before implementing it. See the Phase 4 proposal.
  • 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.
  • Retire the pre-release migration fixture matrix once its source format was confirmed never to have shipped.
  • Make efo init create HEAD, index, worktree, and format-1.0 manifest transactionally without a migration step.
  • Add durable single-file transaction journaling, exclusive writer locks, lock inspection/break primitives, and deterministic interrupted-write recovery.
  • Extend transactions across ordered multi-file commits with rollback copies and a manifest-last commit point.
  • Remove the obsolete migration rollback surface and retain transaction recovery for interrupted writes.
  • Implement worktree/index-aware status, diff, stage, and both restore directions without changing immutable epochs.
  • Implement committed epochs, log, reviewable and conflict-safe revert, backed-up prune-future, and explicit previewed reset --hard destruction.
  • 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

  • Approve the separate-binary architecture and read-only first-pass scope.
  • Define keyboard navigation, compact-layout, accessibility, and terminal restoration requirements.
  • Add the efo-tui workspace binary without coupling lib_efo to a terminal framework.
  • Render HEAD/index/worktree status and all entity collections.
  • Provide collection, entity, and detail navigation with contextual help.
  • Report unsupported, corrupt, locked, and interrupted repositories with the next useful CLI command.
  • Unit test state transitions and deterministic rendering with a test backend.
  • Document installation, startup, keys, scope, and CLI fallback paths.
  • 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

  • Define cumulative event/settlement/region/world generation levels.
  • Choose embedded defaults plus explicit local --config overrides.
  • Define seeded reproducibility, preview/apply behavior, and restoration.
  • Add a versioned WorldGenConfig with strict semantic validation.
  • Move canonical defaults to lib_efo/assets/worldgen/default.json and embed them in the library.
  • Generate deterministic IDs, positions, names, events, and entity counts from a caller-supplied seed without thread-local randomness.
  • Add efo gen world --level ... --seed ... [--config ...] [--apply] with preview as the default and worktree-only application.
  • Add seed-replay, invalid-config, invariant, and CLI reversal tests.
  • 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

  • Add stable, validated road edges between positioned place entities.
  • Model resident, roaming, and travelling character states without overloading governance links.
  • Implement deterministic shortest-time routing with road speed and slower direct-travel fallback.
  • Preview travel plans and advance progress only through staged simulation ticks with clear restore/revert guidance.
  • Exercise disconnected, cyclic, duplicate, malformed, and legacy topology in deterministic tests; broader cargo-fuzz targets remain release hardening.

Checkpoint 3 — spatial event diffusion

  • Define event origins, speed, frontier, affected-set, and expiry data.
  • Diffuse over roads and slower direct distance using configured coefficients and deterministic tie-breaking.
  • Preview each tick with route/reason output before applying it.
  • Test repeated application, convergence, expiry, disconnected graphs, and deterministic replay across many seeds.

Checkpoint 3.5 — tracker simulation resolution (#9, #8, #12)

  • Approve the shared prework contract in docs/resolution-conflict-design.md.
  • Add a separately versioned, embedded AdjudicationConfig with strict validation, external replacement, safety limits, and release packaging.
  • 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.
  • Implement all six stable master-assigned levels, explicit effects, disposition-controlled attenuation, clamping, and stale-checkable reports.
  • Persist idempotent, stale-state-checked adjudication records with workspace and historical fsck validation.
  • 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.
  • 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.
  • 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.
  • Resolve diffusion arrivals against protected towns and configured blockers, explaining avoided/dampened/destroyed outcomes.
  • Resolve resident and positioned characters deterministically; document the initial policy for characters currently in transit.
  • Add generic multi-side conflict records, participant validation, pure fight/war round resolution, victory, stalemate, and explicit ending.
  • 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.
  • 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)

  • 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:

  • 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

  • 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).

  • Add ephemeral UUID/name EntityIndex lookup and duplicate detection while preserving ordered vectors as the stable repository representation (#6).

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

  • Add focused EpochInfo collection, lookup, link, replacement, and position tests; document and provide a runnable lib_efo repository example.

  • Configure Tarpaulin around its subprocess-attribution limitation and refresh rust_autobadges at a directly measured coverage level above 70%.

TUI release-readiness pass

  • Add searchable, sorted entity lists and HEAD/index/worktree browsing.

  • Improve detail rendering, bounded scrolling, paging, and compact layouts.

  • Preserve selection on reload and expose full reload diagnostics.

  • Harden terminal lifecycle, Ctrl-C, non-terminal startup, and no-colour output.

  • 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

  • Default entity/event details to a readable, sectioned presentation.
  • Toggle formatted/raw JSON with v, preserving selection and resetting scroll.
  • 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

  • Add forms for all six entity collections, validation, save previews, and draft cancellation.
  • Save only the worktree through library transactions with locked stale-state checks.
  • Add previewed one-step undo preserving the exact prior entity, including unstaged edits.
  • Cover creation/edit/undo, lock/conflict/failure paths, modal input and terminal workflows.
  • 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.