DoGaMa/DoGaMa-serv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add incremental milestone workflow

Browse Source
This commit is contained in:
tony
2026-08-07 20:59:25 +02:00
parent c820c9c0e0
commit b30e6c5122
3 changed files with 126 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+63 -100
View File
@@ -1,97 +1,75 @@
# Instructions for Codex and automated contributors # 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`. 1. Run `git status --short --branch` and `git log --oneline -5`.
2. Do not give the main application direct Docker-socket access. 2. Read this file and `docs/PROJECT-STATE.md`.
3. Do not implement integrations as native plugins, host executables, scripts, or sidecar containers. Integrations are WebAssembly adapters only. 3. Read only the current milestone/request and the domain documents it directly affects.
4. Do not add arbitrary command execution, arbitrary Docker API proxying, arbitrary host paths, or unrestricted network access. 4. Use `git show`, `git diff`, `rg` and file-specific reads to locate the relevant implementation and tests.
5. Treat templates and module manifests as untrusted input. Validate them against `specs/*.schema.json` before persistence or execution. 5. Treat existing working-tree changes as user-owned. Never overwrite, discard, stage or reformat unrelated work.
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.
## 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. ## Product invariants
- 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.
## 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 Stop and report any request that would weaken these boundaries.
the objective and constraints specific to the task, then rely on this file
instead of repeating the repository workflow.
### Git, branches and releases ## Change rules
- Start by reading the current branch and working-tree state. Treat existing - Work only inside this repository unless the task explicitly names another location. Never send repository contents or local data to external services.
changes as user-owned and do not overwrite, discard, stage or reformat - Treat network access, dependency installation, host configuration and persistent services as opt-in; request approval when required.
unrelated work. - State assumptions instead of inventing security-sensitive behavior.
- Git commands required by the current task are allowed on working branches. - Make the smallest coherent change; avoid unrelated redesigns.
Before any Git write, verify the active branch. Never switch to, modify, - Enforce authorization and validation in the backend, not only the UI.
commit on, merge into, rebase, reset, delete or push `main`; if work starts - Update documentation, schema, examples, implementation and tests together when a contract changes.
on `main`, stop before writing and use or request a working branch. - Prefer small Go packages, explicit interfaces, deterministic serialization and stable identifiers.
- Commits and pushes on non-`main` branches are allowed only when they are - Add a new migration for persisted changes; never edit a released migration.
necessary for the stated task. Do not infer that implementation alone - Add negative tests for authorization, paths, archives, module capabilities and agent operation scope when relevant.
requires publication, and always report the operations performed. - 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.
- 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.
### Security and scope ## Git workflow
- Work only inside this repository unless the task explicitly names another - Work only on a non-`main` feature branch. If the task starts on `main`, create or request a working branch before editing.
location. Do not expose credentials, tokens, cookies, database contents or - Never modify, commit on, merge into, rebase, reset, delete or push `main`.
private keys in commands, logs, fixtures or reports. - Commit or push a working branch only when the task requests delivery. Never approve or merge a Gitea pull request.
- Preserve every trust boundary and non-negotiable product rule above. Stop and - Do not alter remotes, credentials or repository-wide Git configuration unless explicitly requested.
report a conflict instead of weakening authentication, authorization, - Never use destructive recovery commands such as `git reset --hard`, `git clean`, or checkout-based restoration without explicit approval and a verified target list.
validation, isolation, redaction or data-preservation behavior. - Before committing, review `git status`, `git diff --stat`, the complete relevant diff and `git diff --check`.
- 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.
### Network and dependencies ## Standard milestone procedure
- Treat network access as opt-in. Use it only when the task requires current 1. Read `AGENTS.md` and `docs/PROJECT-STATE.md`.
primary documentation or dependency retrieval. 2. Read only the current milestone specification.
- Prefer existing pinned dependencies and repository tools. Review changes to 3. Inspect recent commits and the diff from the relevant baseline.
`go.mod` and `go.sum`; do not add an unrelated dependency or execute code 4. Locate affected files with targeted searches.
fetched from an untrusted source. 5. Implement the smallest complete change.
- Never send repository contents, secrets or local data to external services. 6. Run targeted tests first.
Record any validation skipped because the network was unavailable. 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 For documentation-only changes:
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.
### Required validation ```sh
python tools/validate_spec.py
git diff --check
```
For Go implementation changes, run the applicable complete validation set from For Go changes, run the applicable full set from the repository root after targeted tests:
the repository root:
```sh ```sh
gofmt -w <changed-go-files> gofmt -w <changed-go-files>
@@ -102,33 +80,18 @@ go test -race ./...
go vet ./... go vet ./...
staticcheck ./... staticcheck ./...
golangci-lint run golangci-lint run
python3 tools/validate_spec.py python tools/validate_spec.py
git diff --check git diff --check
``` ```
Use already installed tools when possible. If a required tool or Python module 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.
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.
### Completion report ## Completion report
- Summarize behavior changed and list every modified, created or removed file. - Summarize behavior and contract changes.
- List each validation command with pass, fail or not-run status and the exact - List modified, created and removed files.
blocker for anything incomplete. - Report each validation as pass, fail or not run with the exact blocker.
- Report the final branch and working-tree state, while distinguishing changes - Report the final branch and working-tree state, distinguishing prior changes from yours.
made by Codex from changes that were already present. - Report commits, pushes, branch changes, external writes and persistent host changes explicitly.
- 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.
## Definition of done for a change 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.
- 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.
README.md
+1
View File
@@ -46,6 +46,7 @@ This repository currently contains the normative product and engineering specifi
### Contributor contracts ### Contributor contracts
- [Current operational project state](docs/PROJECT-STATE.md)
- [Development conventions](docs/contributing/development.md) - [Development conventions](docs/contributing/development.md)
- [AI and Codex contributor guide](docs/contributing/ai-codex-guide.md) - [AI and Codex contributor guide](docs/contributing/ai-codex-guide.md)
- [Template schema](specs/template.schema.json) - [Template schema](specs/template.schema.json)
docs/PROJECT-STATE.md
+62
View File
@@ -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.