From 6aae41d36fb68b0ac7bb0acf1835310b457122a3 Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Mon, 31 Aug 2026 00:09:36 +0200 Subject: [PATCH] docs: add graph-backed agent guide --- AGENTS.md | 196 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 178 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3aee22c..2522196 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,11 +3,58 @@ 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: +## Start here and sources of truth + +Begin with `docs/README.md`, then follow it to `docs/DEVELOPER_INDEX.md`. The +developer index is the shortest current map from a feature request to its code, +focused contract, tests, and known incomplete work. + +When sources disagree, use this order: + +1. Current code and focused tests establish implemented behavior; they do not + silently supersede an architectural decision. +2. Applicable Accepted records in `docs/decisions/` define durable architecture + within their stated scope until another Accepted record explicitly + supersedes them. Treat conflicting code as drift to fix or document. + `docs/ARCHITECTURE_OVERVIEW.md` is the current ownership/dependency map. +3. `docs/DEVELOPER_INDEX.md` and the focused architecture/schema guides define + the current documented contract. +4. `docs/LEARNING_ROADMAP.md` defines sequencing, not runtime truth. + +Fix the smallest authoritative document after changing behavior. Do not create +a second implementation in prose or copy the same status table into many docs. + +## Codebase discovery with codebase-memory + +This repository is indexed as +`Users-rijadzuzo-dev-private-gamedev-the-steward` in codebase-memory. Treat the +name as a lookup hint, not proof that the graph is current. + +- At session start, after a pull, and after changing branches, call + `list_projects` and `index_status`. Confirm the indexed root, branch, and HEAD + match the checkout; re-index after a large or external update. +- Use Verify/Tier 2 evidence by default: `search_graph` to find exact symbols, + `trace_path` in the material direction, and `get_code_snippet` for source. + Use `get_architecture` only for orientation, not as a substitute for exact + code. +- Check `has_more`/cursors and paginate relevant results. After candidate files + are known, call `check_index_coverage` once with every evidence path. +- A clean coverage result is best-effort, not proof of completeness. Read exact + source for partial, skipped, excluded, stale, pending, or unknown ranges. +- Use `rg` for string literals, resource paths, scene/config files, generated + data, and graph coverage gaps. Do not make negative or exhaustive claims from + a provisional graph search. +- Before a refactor, use `detect_changes` or inbound traces to inspect the blast + radius. Re-run focused searches after edits rather than relying on this file + as a frozen graph dump. + ## 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. + - Start with `docs/README.md` and `docs/DEVELOPER_INDEX.md`. + - Use `docs/DEVELOPER_INDEX.md` for current status and open gaps. + - Use `docs/LEARNING_ROADMAP.md` for milestone sequencing and exit tests; + reconcile any candidate slice with current code and focused tests. - 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 @@ -37,7 +84,7 @@ Use the project quality gate for the current platform: powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1 ``` -For changed-file quick checks: +To narrow formatter/linter scope to changed GDScript files: ```bash ./tools/quality.sh --changed @@ -47,18 +94,69 @@ For changed-file quick checks: powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1 -Changed ``` +`--changed` narrows only the `gdformat` and `gdlint` file set. It still runs the +Godot import/parser check, every headless scenario, the compatibility-renderer +scenario, and GUT. Use it only while iterating; run the full current-platform +gate before every commit. + 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 +```bash git diff --check ``` -If touching `main.tscn` or runtime wiring, also do a direct Godot 4.7 headless -boot when practical. +If changing `project.godot`, `main.tscn`, autoload/plugin configuration, scene +UIDs or node paths, or startup/runtime scene wiring, also run the configured +main scene with the same Godot 4.7 binary used by the gate: + +```bash +"$GODOT_BIN" --headless --path "$PWD" --quit-after 3 +``` + +```powershell +& $env:GODOT_BIN --headless --path (Get-Location).Path --quit-after 3 +``` + +Set `GODOT_BIN` when the gate auto-detected a binary instead. Inspect output as +well as exit status, and accept only diagnostics matching the quality gate's +exact allowlist. Read failures from `logs/quality/latest/`; do not weaken an +allowlist or skip a failing scenario merely to make the gate green. + +## Current codebase map + +Keep this map concise; `docs/DEVELOPER_INDEX.md` owns the detailed feature +matrix and extension workflow. + +- `project.godot` starts `main.tscn`. The main scene wires the authored Jajce + world, player, `ActiveWorldAdapter`, `SimulationManager`, + `SaveSlotController`, `WorldViewManager`, and UI surfaces. +- `simulation/SimulationManager.gd` is the scene-tree facade and deterministic + tick boundary. It advances regional authority before committing the local + tick, then coordinates focused systems rather than duplicating their rules. +- `simulation/actions/`, `simulation/commands/`, and `simulation/economy/` own + selection/execution, target resolution, shared player/NPC command contracts, + and exact inventory or storage transactions. +- `simulation/events/`, `simulation/knowledge/`, `simulation/relationships/`, + `simulation/opportunities/`, `simulation/situations/`, + `simulation/dialogue/`, and `simulation/quests/` turn completed mutations + into causal facts and derived player-facing projections. +- `simulation/state/` owns versioned primitive records; + `simulation/definitions/` owns immutable definitions and stable IDs; + `simulation/regional/` owns scheduled distant work and caravan authority; + `simulation/persistence/` owns combined manifests and safe slot replacement. +- `world/active_world_adapter.gd` and `world/targets/` own contextual loaded- + world discovery, descriptors, capabilities, and transient handles. Resource, + storage, activity, and animal nodes are providers bound to simulation state. +- `world/world_view_manager.gd`, `world/presentation/`, `world/jajce/`, + `world/ui/`, and `player/` own input, geometry, navigation, and visible + feedback. They submit commands or report facts; they do not author saves. +- `tests/` contains deterministic headless scenarios and GUT tests; + `simulation/benchmark/` and `docs/benchmarks/` contain reproducible workload + evidence; `tools/` contains the cross-platform quality gate. ## Architecture direction @@ -73,12 +171,29 @@ Preserve the simulation/presentation boundary. `ActionTargetResolver`. - Visual movement belongs to `WorldViewManager`/`NpcVisual`; decision and task execution belong to the simulation systems. +- Player and NPC callers use the same commands and capabilities. Revalidate the + actor, target, context, range, revision, cost, and permission at execution; + mutate atomically before recording facts or deriving projections. +- Target handles, generation tokens, spatial/population indexes, presentation + cues, and reason traces are disposable derived state. Persist stable + contextual IDs and primitives, then prove rebuilding derived state preserves + decisions and checksums. +- A local tick may advance only after the regional facade succeeds. Regional + work must remain deterministic, bounded, fail-closed, and rollback-safe. +- When regional authority exists, save and restore must use the combined + manifest and remain all-or-nothing. Preserve schema validation, size bounds, + restore rollback, temporary-file validation, and the atomic + temporary/backup/final replacement path; a failed restore emits no success + notification. 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 +These agent-facing guardrails summarize ADR 0001 and ADR 0002. The Accepted +records remain authoritative within their stated scopes. + 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. @@ -134,14 +249,16 @@ 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. +- resources: immutable resource definitions plus authoritative + `ResourceStateRecord`; `ResourceNode` is the loaded provider and visual + binding; +- creatures: `CreatureVisual` is the shared navigation/death presentation root; +- enemies: `EnemyDefinition`/`SimulationEnemies` provide typed content, + `CombatantFactory` and `ConflictSystem` own authoritative instances and + lifecycle, and `HostileCombatant` presents them; +- animals: `AnimalDefinition`, `AnimalStateRecord`, `AnimalFactory`, and + `AnimalCareSystem` own content and lifecycle; `AnimalNode` is the loaded + interaction/navigation binding. 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. @@ -159,6 +276,19 @@ Resource additions should preserve: Storage uses `StorageNode`. Rest, study, and patrol use `ActivitySite`. Do not turn these back into generic marker zones. +## Vendored dependencies and Godot asset hygiene + +- Treat `addons/dialogue_manager`, `addons/gut`, and `addons/terrain_3d` as + pinned vendor code. Do not reformat, refactor, or update them unless the task + explicitly owns that dependency. +- Preserve the complete cross-platform Terrain3D payload checked by the quality + gate. Do not replace a missing platform binary with a local-only artifact. +- Preserve `.uid` files, `class_name` locations, resource UIDs, and scene paths + when moving Godot scripts or scenes. Use `git mv` for intentional moves and + prove them with import plus headless startup. +- Never commit `.godot/`, `.venv/`, `logs/quality/`, or generated local editor + state. Do not hand-edit imported cache files to hide an error. + ## Testing expectations Add or update headless scenarios when a change affects: @@ -169,19 +299,34 @@ Add or update headless scenarios when a change affects: - navigation/reachability assumptions; - player/NPC parity; - deterministic continuation; +- regional job ordering, rollback, or local/regional tick coordination; +- combined-manifest save/restore, migration, or atomic slot behavior; +- event causality, knowledge, situation, dialogue, or quest projections; - UI/debug state that represents real simulation facts. Keep tests deterministic. Prefer fixed seeds and stable IDs. +Any persistent-state change requires an explicit schema/migration decision, +exact validation, checksum and tamper coverage, rollback coverage, and a +deterministic continuation test. ## Documentation expectations Update docs when the implemented behavior changes the roadmap, architecture, or current contract. Keep updates local: +- `docs/DEVELOPER_INDEX.md` for the current feature map, extension routes, and + deliberately incomplete work; +- `docs/ARCHITECTURE_OVERVIEW.md` for ownership and dependency boundaries; +- `docs/PROJECT_CONTEXT.md` only when product intent or active constraints + change; dated implementation passages are historical context; - `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/ACTION_SYSTEM_ARCHITECTURE.md`, `docs/ECONOMIC_EVENTS.md`, and + `docs/REGIONAL_SIMULATION.md` for their focused runtime contracts; +- `docs/FEATURE_*.md` only when the corresponding implementation/extension + guide changes; - `docs/BUILD_IN_PUBLIC_PLAN.md` for Jajce/demo/readability slices; - `docs/decisions/` only for durable architectural decisions. @@ -190,16 +335,31 @@ 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. +Preserve user changes. Check `git status --short --branch` before editing and +before committing, inspect the branch/upstream and recent history, and stage +only the files owned by the current slice. Do not use destructive cleanup +commands unless explicitly asked. -Use conventional commits, for example: +Every repository commit must use Conventional Commits with an imperative, +specific summary: `(optional-scope): summary`. Common types are `feat`, +`fix`, `docs`, `test`, `refactor`, `perf`, `build`, `ci`, `chore`, and `merge`. +Examples: - `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. +Before committing, review `git diff`, run `git diff --check` and the full +current-platform quality gate, then review `git diff --cached`. Validation is +explicit; do not assume a local hook ran it. One coherent vertical slice may +include its implementation, deterministic tests, required `.uid`/resource +files, and smallest necessary documentation update. Split unrelated fixes, +never stage pre-existing user work, and never use `--no-verify` to bypass a +repository gate. + +Do not amend, rebase, drop, or fold user-owned commits unless explicitly asked. +Do not push implicitly. After committing, report the commit hash and the real +ahead/behind or remote-sync state. ## Product taste