Merge pull request 'docs: add incremental milestone workflow' (#9) from codex/docs-incremental-workflow into main

Reviewed-on: #9

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 <changed-go-files>
@@ -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.

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)

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.