From b30e6c51223f333775ab225806c8e1eaa78d8435 Mon Sep 17 00:00:00 2001 From: Tony Date: Fri, 7 Aug 2026 20:59:25 +0200 Subject: [PATCH] docs: add incremental milestone workflow --- AGENTS.md | 163 ++++++++++++++++-------------------------- README.md | 1 + docs/PROJECT-STATE.md | 62 ++++++++++++++++ 3 files changed, 126 insertions(+), 100 deletions(-) create mode 100644 docs/PROJECT-STATE.md diff --git a/AGENTS.md b/AGENTS.md index 6ee883f..e41a93d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,97 +1,75 @@ # Instructions for Codex and automated contributors -Read `README.md` and the relevant documents under `docs/` before changing implementation or contracts. +Work incrementally. Do not perform a repository-wide audit unless the user explicitly requests one. -## Non-negotiable rules +## Start every task -1. Preserve the product invariants in `README.md`. -2. Do not give the main application direct Docker-socket access. -3. Do not implement integrations as native plugins, host executables, scripts, or sidecar containers. Integrations are WebAssembly adapters only. -4. Do not add arbitrary command execution, arbitrary Docker API proxying, arbitrary host paths, or unrestricted network access. -5. Treat templates and module manifests as untrusted input. Validate them against `specs/*.schema.json` before persistence or execution. -6. Keep secrets out of API responses, logs, audit payloads, exports, error messages, and test fixtures. -7. Preserve player data and backups by default in every deletion, update, restore, and migration workflow. -8. Keep `compose.yaml` minimal. Product settings belong in the database and web interface unless they are bootstrap secrets, bind roots, or network/listen settings required before startup. -9. SQLite is the V1 database. Do not introduce an external database, message broker, Kubernetes, or distributed-node design without an accepted architecture decision. -10. Palworld is the reference integration. Any contract change affecting templates, modules, backups, permissions, or instance lifecycles must be checked against both Palworld examples. +1. Run `git status --short --branch` and `git log --oneline -5`. +2. Read this file and `docs/PROJECT-STATE.md`. +3. Read only the current milestone/request and the domain documents it directly affects. +4. Use `git show`, `git diff`, `rg` and file-specific reads to locate the relevant implementation and tests. +5. Treat existing working-tree changes as user-owned. Never overwrite, discard, stage or reformat unrelated work. -## Change workflow +Do not reread all documentation, list every source file, concatenate large files, or emit thousands of log lines when a targeted query is sufficient. Start with targeted tests and concise output; expand diagnostics only after a failure. -- Locate the normative document first. -- State assumptions when requirements are ambiguous; do not silently invent security-sensitive behavior. -- Update documentation, schema, example, implementation, and tests together when a contract changes. -- Prefer small Go packages with explicit interfaces and dependency direction. -- Add migrations for persisted data changes. Never edit an already released migration. -- Use deterministic serialization and stable identifiers. -- Validate JSON Schemas and YAML examples in automated checks. -- Add negative tests for authorization, path validation, module capabilities, archive extraction, and agent operation scope. -- Report what was validated and what still needs physical or integration testing. +## Product invariants -## Codex operating workflow +- The main application never accesses the Docker socket. Only the private restricted agent does. +- Integrations are WebAssembly adapters only: no native plugins, host scripts, executables or sidecars. +- Never add arbitrary commands, Docker API proxying, host paths or unrestricted network access. +- Validate untrusted templates and manifests against `specs/*.schema.json`. +- Never expose secrets in APIs, logs, audit events, exports, errors or fixtures. +- Preserve player data and backups by default in deletion, update, restore and migration workflows. +- Keep `compose.yaml` minimal; ordinary product settings belong in SQLite and the web UI. +- SQLite is the V1 database. Keep the single-host architecture unless an accepted decision changes it. +- Palworld is the reference integration. Check both Palworld examples when a contract affects templates, modules, backups, permissions or instance lifecycle. -These rules are permanent repository policy. A `codex exec` prompt should name -the objective and constraints specific to the task, then rely on this file -instead of repeating the repository workflow. +Stop and report any request that would weaken these boundaries. -### Git, branches and releases +## Change rules -- Start by reading the current branch and working-tree state. Treat existing - changes as user-owned and do not overwrite, discard, stage or reformat - unrelated work. -- Git commands required by the current task are allowed on working branches. - Before any Git write, verify the active branch. Never switch to, modify, - commit on, merge into, rebase, reset, delete or push `main`; if work starts - on `main`, stop before writing and use or request a working branch. -- Commits and pushes on non-`main` branches are allowed only when they are - necessary for the stated task. Do not infer that implementation alone - requires publication, and always report the operations performed. -- Codex may create merge/pull requests from working branches when delivery - requires review. Codex must never approve or merge them; leave approval and - fusion into `main` to an authorized user in Gitea. -- Do not alter remotes, credentials or repository-wide Git configuration - unless the task explicitly requires it. -- Never use destructive recovery commands such as `git reset --hard`, - `git clean`, or checkout-based file restoration without explicit approval - and a verified target list. +- Work only inside this repository unless the task explicitly names another location. Never send repository contents or local data to external services. +- Treat network access, dependency installation, host configuration and persistent services as opt-in; request approval when required. +- State assumptions instead of inventing security-sensitive behavior. +- Make the smallest coherent change; avoid unrelated redesigns. +- Enforce authorization and validation in the backend, not only the UI. +- Update documentation, schema, examples, implementation and tests together when a contract changes. +- Prefer small Go packages, explicit interfaces, deterministic serialization and stable identifiers. +- Add a new migration for persisted changes; never edit a released migration. +- Add negative tests for authorization, paths, archives, module capabilities and agent operation scope when relevant. +- Open detailed documents under `docs/` only when their domain is affected. `README.md` is required only when product invariants, the documentation map or top-level status changes. -### Security and scope +## Git workflow -- Work only inside this repository unless the task explicitly names another - location. Do not expose credentials, tokens, cookies, database contents or - private keys in commands, logs, fixtures or reports. -- Preserve every trust boundary and non-negotiable product rule above. Stop and - report a conflict instead of weakening authentication, authorization, - validation, isolation, redaction or data-preservation behavior. -- Inspect before editing, make the smallest coherent change, and preserve - user-owned changes. Do not modify generated or synchronized files unless the - repository documents that workflow. -- Do not install system packages, start persistent services, modify host - configuration or use elevated privileges without explicit approval. +- Work only on a non-`main` feature branch. If the task starts on `main`, create or request a working branch before editing. +- Never modify, commit on, merge into, rebase, reset, delete or push `main`. +- Commit or push a working branch only when the task requests delivery. Never approve or merge a Gitea pull request. +- Do not alter remotes, credentials or repository-wide Git configuration unless explicitly requested. +- Never use destructive recovery commands such as `git reset --hard`, `git clean`, or checkout-based restoration without explicit approval and a verified target list. +- Before committing, review `git status`, `git diff --stat`, the complete relevant diff and `git diff --check`. -### Network and dependencies +## Standard milestone procedure -- Treat network access as opt-in. Use it only when the task requires current - primary documentation or dependency retrieval. -- Prefer existing pinned dependencies and repository tools. Review changes to - `go.mod` and `go.sum`; do not add an unrelated dependency or execute code - fetched from an untrusted source. -- Never send repository contents, secrets or local data to external services. - Record any validation skipped because the network was unavailable. +1. Read `AGENTS.md` and `docs/PROJECT-STATE.md`. +2. Read only the current milestone specification. +3. Inspect recent commits and the diff from the relevant baseline. +4. Locate affected files with targeted searches. +5. Implement the smallest complete change. +6. Run targeted tests first. +7. Run the applicable global validations. +8. Update `docs/PROJECT-STATE.md` with the new baseline, delivered behavior, durable decisions, limitations and next work. +9. Review and report the final diff and validation status. -### Caches and temporary files +## Validation -- Keep Codex-created caches and temporary artifacts outside tracked source - paths, preferably under `.cache/codex/` or an OS temporary directory. -- Reuse caches when safe. Do not delete or purge shared Go, Python, linter, - container or user caches unless explicitly requested. -- Do not leave binaries, databases, coverage files, logs or temporary patches - in the repository. Before finishing, remove only artifacts created by the - current task and confirmed safe to remove. +For documentation-only changes: -### Required validation +```sh +python tools/validate_spec.py +git diff --check +``` -For Go implementation changes, run the applicable complete validation set from -the repository root: +For Go changes, run the applicable full set from the repository root after targeted tests: ```sh gofmt -w @@ -102,33 +80,18 @@ go test -race ./... go vet ./... staticcheck ./... golangci-lint run -python3 tools/validate_spec.py +python tools/validate_spec.py git diff --check ``` -Use already installed tools when possible. If a required tool or Python module -is unavailable, do not silently install it or omit the check: report the exact -blocker and request approval when installation or network access is needed. -Run narrower tests during development, but run the full applicable set before -declaring completion. A passing build does not replace tests, race detection, -static analysis or specification validation. +Use installed tools and pinned dependencies. Do not silently install missing tools; report the exact blocker. Keep caches under `.cache/codex/` or an OS temporary directory and remove only artifacts created by the current task. -### Completion report +## Completion report -- Summarize behavior changed and list every modified, created or removed file. -- List each validation command with pass, fail or not-run status and the exact - blocker for anything incomplete. -- Report the final branch and working-tree state, while distinguishing changes - made by Codex from changes that were already present. -- State explicitly whether commits, tags, pushes, branch changes, external - writes or persistent host changes occurred. Never claim success for a check - that was not run to completion. +- Summarize behavior and contract changes. +- List modified, created and removed files. +- Report each validation as pass, fail or not run with the exact blocker. +- Report the final branch and working-tree state, distinguishing prior changes from yours. +- Report commits, pushes, branch changes, external writes and persistent host changes explicitly. -## Definition of done for a change - -- Relevant requirements and acceptance criteria are satisfied. -- Authorization is enforced in the backend, not only hidden in the UI. -- Audit and notification behavior is deliberate. -- Failure and rollback behavior is covered. -- Documentation and machine-readable examples agree. -- Tests cover success, denial, and interruption paths. +A change is complete only when success, denial and interruption behavior relevant to its scope are deliberate, documentation and machine-readable contracts agree, and unfinished integration or physical validation is reported. diff --git a/README.md b/README.md index 50feb3e..a72c1a4 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ This repository currently contains the normative product and engineering specifi ### Contributor contracts +- [Current operational project state](docs/PROJECT-STATE.md) - [Development conventions](docs/contributing/development.md) - [AI and Codex contributor guide](docs/contributing/ai-codex-guide.md) - [Template schema](specs/template.schema.json) diff --git a/docs/PROJECT-STATE.md b/docs/PROJECT-STATE.md new file mode 100644 index 0000000..b345da4 --- /dev/null +++ b/docs/PROJECT-STATE.md @@ -0,0 +1,62 @@ +# DoGaMa project state + +Read this compact operational baseline before starting a milestone. Open detailed domain documents only when the current work affects them. + +## Baseline + +- Current reference: `main` after milestone 7 and `feat(instances): add Docker labels, user IDs, image tags and deferred recreation` (`c820c9c`). +- Released SQLite migrations: `0001` through `0007`; never rewrite them. +- Roadmap milestones 1-7 are implemented. The instance-container configuration feature landed after milestone 7. + +## Architecture + +- Go main application: HTTP API, embedded server-rendered UI, authentication/authorization, SQLite, workflows, backups and WASM runtime. +- Private restricted Go agent: sole Docker-socket owner; authenticated typed API; registered-instance and plan-digest binding; no generic Docker proxy. +- Integrations: capability-scoped WebAssembly adapters only. Palworld REST is the reference module. +- Data: SQLite plus canonical allowed server, import and backup roots. Persistent game data lives outside containers. +- Contracts: declarative YAML templates and module manifests validated against JSON Schemas; released snapshots are immutable. + +## Implemented capabilities + +- Bootstrap administrator, local authentication, secure sessions and CSRF protection. +- Validated embedded catalog, deterministic deployment previews and instance registry. +- Restricted instance create/inspect/start/stop/restart/delete and reconciliation. +- Per-instance memberships, overrides and installation requests with backend authorization. +- Backup scheduling/retention, safe imports, export and restore with safety backups. +- Sandboxed WASM runtime and normalized module API with Palworld reference adapter. +- Game-container configuration: global and per-instance labels, safe label variables, derived instance slug, immutable Docker-user selection, tracked/pinned image tags, immediate or deferred container recreation, and public game-icon route. + +## Durable decisions + +- Editable Docker labels apply only to game-server instance containers. +- Labels on the DoGaMa application container remain Compose configuration and are never read, copied or edited by DoGaMa. +- Merge order is global labels, then instance labels; instance values win. Internal technical labels are applied last and cannot be overridden. +- `dogama.*` and `io.dogama.*` are reserved label namespaces. +- Label values support only the explicit allowlist in `internal/instance/container_config.go`; unknown variables are errors, not arbitrary templates. +- `{{game.icon_url}}` is the public icon for the game. `{{instance.slug}}` remains supported. +- Instance slugs are derived from the display name, not canonical IDs. Accents are normalized to ASCII; whitespace, `/`, punctuation and special characters become safe hyphen separators; repeated and edge hyphens are removed. +- Docker user mode is fixed at creation to DoGaMa UID/GID, custom numeric UID/GID, or image-defined user. Never perform automatic recursive ownership changes. +- A pinned image tag is an explicit mutable tag, not an immutable digest. Tracked mode follows the template's declared default tag. +- Replacement-requiring changes use the generic `container_config_pending` desired-versus-applied state. Replacements preserve bind-mounted data and prior running/stopped intent. +- The main app never gains Docker-socket access; the agent remains deny-by-default and independently validates privileged plan fields. + +## Known limitations and debt + +- Roadmap milestone 8 remains broader than the delivered instance-container configuration: controlled update history, mods and rollback paths are not complete. +- Notification channels, audit delivery/retention UI and release hardening remain roadmap work. +- The web interface is intentionally modest; several advanced workflows are API-first. +- Linux is the deployment target. Native Windows execution of the full Go suite is blocked by Unix `Statfs` code; use Linux/WSL/CI for complete execution. +- `staticcheck`, `golangci-lint` and Python specification dependencies may not be installed on every development host; report missing tooling rather than silently skipping or installing it. + +## Validation and CI + +- No repository-hosted Gitea/GitHub workflow files are currently present. +- Normal completion gate for Go changes is the validation set in `AGENTS.md` on Linux. +- Specification validation is `python tools/validate_spec.py` with `tools/requirements-validation.txt` available. +- Start with package/file-specific tests, then run global tests, build, race detection, vet, static analysis and schema validation as applicable. + +## Next known work + +- Roadmap milestone 8: controlled game updates, configuration history and rollback; complete mod configuration only within declarative safe contracts. +- Then milestone 9: notifications and light audit trail. +- Update this file at the end of every merged milestone or durable architectural change; keep it compact and remove stale statements.