gamedev-the-steward/AGENTS.md

# Agent working guide for The Steward

This repository is a Godot 4.7 simulation prototype. Treat it as a living
systems project, not a content dump. The expected working style is:

## Default development loop

1. Read the relevant roadmap/docs before changing code.
   - Start with `docs/README.md`.
   - Use `docs/LEARNING_ROADMAP.md` for the current next item.
   - Use focused plans such as `docs/RESOURCE_NODE_MIGRATION.md` only within
     their stated scope.
2. Inspect the current code and tests before assuming roadmap status is still
   accurate. The user often changes things in parallel.
3. Implement the smallest useful vertical slice.
   - Prefer functional systems progress over broad polish.
   - Avoid deep rabbit holes unless the current slice needs them.
   - Keep Jajce visual/design work bounded; prioritize simulation behavior,
     validation, WorldEnvironment ambience, and readable presentation.
4. Validate with the local quality gate.
5. Update the smallest relevant docs after completing a phase or decision.
6. Commit with a conventional commit message.

## Validation

Only Godot 4.7 matters for this project.

Use the project quality gate for the current platform:

```bash
# macOS / Linux
./tools/quality.sh
```

```powershell
# Windows
powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1
```

For changed-file quick checks:

```bash
./tools/quality.sh --changed
```

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1 -Changed
```

The quality scripts isolate Godot's user profile under `logs/quality/godot_profile`
so headless Godot 4.7 can run without crashing when platform user-data paths
are unavailable. Do not remove that behavior.

Useful extra checks:

```powershell
git diff --check
```

If touching `main.tscn` or runtime wiring, also do a direct Godot 4.7 headless
boot when practical.

## Architecture direction

Preserve the simulation/presentation boundary.

- Simulation state owns authority: resources, storage, NPC inventory, events,
  task state, target IDs, positions, RNG streams, and save records.
- World nodes are presentation and interaction geometry. They may register or
  bind state, but they should not become the only owner of persistent facts.
- NPCs store stable IDs, not `NodePath`s or node references.
- Target discovery should go through `ActiveWorldAdapter` and
  `ActionTargetResolver`.
- Visual movement belongs to `WorldViewManager`/`NpcVisual`; decision and task
  execution belong to the simulation systems.

When adding a system, first prove the contract with one real gameplay use case.
Do not extract generic frameworks before multiple real consumers justify them.

## Emergent-world doctrine

The game world is the source of narrative truth. Dialogue, tasks, quests, and
visible happenings must arise from ordinary simulation state and events rather
than maintaining parallel scripted copies.

- Keep immutable definitions, authored instance placement, mutable state,
  systems, and presentation as separate layers.
- Persist stable IDs and primitive data only. Saved state must never contain
  scripts, nodes, `NodePath`s, callables, or resource paths.
- Mutate authoritative state before recording the fact that describes the
  mutation. Facts may reference exact causes; they may not stand in for a
  missing world change.
- Treat dialogue prose as presentation. Semantic intents, selected response
  IDs, action commands, commitments, and their causal world events are the
  authoritative contract.
- Treat quests as player-facing projections of real unresolved situations.
  Never create quest-only enemies, items, damage, relationships, resources, or
  completion facts.
- Route player and NPC interactions through the same authoritative action and
  capability contracts. Presentation can suggest or submit a command, but the
  simulation must revalidate it.
- Loaded visuals must not decide whether travel, work, growth, or distant
  conflict completes. Presentation interpolates authoritative state and may
  report local feasibility or obstruction.
- Every generated action, situation, helper, dialogue intent, or consequence
  must expose a concise reason trace with the definition and causal fact IDs
  that justified it.
- “Data-only content” means new combinations of existing typed predicates,
  capabilities, effects, behavior profiles, and presentation cues. A genuinely
  new mechanic adds one bounded reusable handler and tests; it does not add one
  script per item, creature, quest, or conversation.
- Prefer typed Godot resources, composition, deterministic registries, and
  explicit strategy handlers. Do not introduce a universal reflection DSL or
  rewrite the project as a full ECS.

The intended extension path is therefore definition plus content pack, optional
presentation cue, and authored placement or simulation spawn. A berry, bear,
caravan, shortage, or conversation topic should reuse the same state, action,
event, and presentation contracts that existing content uses.

## Resource and target rules

Do not reintroduce abstract food/wood task-zone fallbacks.

Current resource gathering should use finite `ResourceNode` instances:

- food: berries, animal camps, village stock, future farms/crops;
- wood: trees, wood piles, future forestry contexts.

## Entity systems pattern

Build every resource, enemy, and animal as a reusable system with shared root
behaviour, not as a one-off object. Add a new type through data/definitions
plus a small behaviour or visual hook, reusing the root for movement,
presentation, serialization, and lifecycle:

- resources: `ResourceNode` + `ResourceStateRecord` (amount, yield, regrowth);
- creatures: `CreatureVisual` shared movement root (navigate to the
  authoritative simulation position, report position, death), with per-type
  visuals built from definitions;
- enemies: `EnemyDefinition` + `SimulationEnemies` registry driving combatant
  spawns and hostile visuals;
- animals: `AnimalNode` + `AnimalStateRecord` following the same
  follow-the-authoritative-position contract.

A new berry, tree, bear, bandit, boar, or goat should be mostly a definition
plus a bounded hook — never a new movement/combat/save system.

Resource additions should preserve:

- stable unique IDs;
- food/wood coverage;
- meaningful placement context;
- reachable interaction points;
- `safety_risk`, `comfort_distance`, and `discovery_priority` metadata;
- clear player interaction ranges so nearby storage/activity/resource targets
  do not overlap accidentally.

Storage uses `StorageNode`. Rest, study, and patrol use `ActivitySite`. Do not
turn these back into generic marker zones.

## Testing expectations

Add or update headless scenarios when a change affects:

- resource conservation;
- target selection or reservations;
- save/load or schema behavior;
- navigation/reachability assumptions;
- player/NPC parity;
- deterministic continuation;
- UI/debug state that represents real simulation facts.

Keep tests deterministic. Prefer fixed seeds and stable IDs.

## Documentation expectations

Update docs when the implemented behavior changes the roadmap, architecture, or
current contract. Keep updates local:

- `docs/LEARNING_ROADMAP.md` for next-item sequencing and milestone status;
- `docs/RESOURCE_NODE_MIGRATION.md` for resource-target migration status;
- `docs/SIMULATION_STATE_SCHEMA.md` for serialized state changes;
- `docs/SIMULATION_DEFINITIONS.md` for action/profession/ID contracts;
- `docs/BUILD_IN_PUBLIC_PLAN.md` for Jajce/demo/readability slices;
- `docs/decisions/` only for durable architectural decisions.

Do not duplicate full status tables across many docs. If docs and code differ,
trust code/tests first, then update docs.

## Git expectations

Preserve user changes. Check `git status --short` before editing and before
committing. Do not use destructive cleanup commands unless explicitly asked.

Use conventional commits, for example:

- `feat: validate expanded resource discovery`
- `fix: stabilize godot 4.7 headless validation`
- `docs: capture agent workflow`

Commit only after validation relevant to the change has passed.

## Product taste

The project is aiming for a readable, magical simulation garden that can grow
into a larger systemic game. Prefer honest visible cause-and-effect:

- NPCs should walk to real resources, storage, and activity sites.
- UI/debug overlays should explain actual simulation state.
- Beauty work should represent real state rather than fake activity.
- Each slice should leave the project easier to reason about than before.