Replace CONSTRAINTS.md with detailed execution model, installer contract, and anti-patterns from devcontainer work

CONSTRAINTS.md

@@ -1,15 +1,43 @@
 # Constraints – zlh-grind
 
-This repository is strictly for **GPT execution context + logs**.
+This repository is strictly for *decision tracking*, *constraints*, and *ground rules*.  
+It is not an implementation repo.
 
-Non-negotiables:
+---
-- Do NOT refactor code here
-- Do NOT invent missing system facts
-- Do NOT redefine system boundaries
-- Do NOT duplicate canonical docs from upstream repos
 
-Operational constraints (ZeroLagHub specific):
+## Execution model constraints
-- We are using **one base template** (`AGENT_TEMPLATE_VMID`) by design.
+- zlh-agent executes installer logic as **embedded scripts**.
-- In current workflow, updating zlh-agent implies building + copying binary into the template container:
+- Embedded scripts must not rely on filesystem-relative paths (`$0`, `dirname`, etc.).
-  - **agent change == template promotion**
+- Any shared logic must be executed in the **same shell session** as its callers.
-- Prefer API-side wire compatibility fixes over agent/template changes unless we intentionally schedule a template rev.
+
+---
+
+## Installer contract constraints
+- Installers must be:
+  - deterministic
+  - artifact-driven
+  - idempotent
+  - strict (`set -euo pipefail`)
+- All runtime installers require explicit environment projection:
+  - `RUNTIME_VERSION` is mandatory
+  - artifact naming may be customized via `ARCHIVE_PREFIX`
+- Installers must not parse JSON or agent state files.
+
+---
+
+## Responsibility boundaries
+- API declares *intent* (runtime, version, container type).
+- Agent translates intent into:
+  - environment variables
+  - filesystem operations
+  - installer execution order
+- Installers perform no orchestration or decision-making.
+
+---
+
+## Anti-patterns (explicitly forbidden)
+- Mega-installers that handle multiple runtimes via branching logic
+- Package-manager–based installs (apt, nvm, pyenv, sdkman)
+- Weakening installer strictness to accommodate agent bugs
+
+---