From a2fc3fc78ae32884e60e4d3b524cdfcc58afb9a3 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Sun, 21 Dec 2025 23:02:38 +0000
Subject: [PATCH] Replace CONSTRAINTS.md with detailed execution model,
 installer contract, and anti-patterns from devcontainer work

---
 CONSTRAINTS.md | 50 +++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 39 insertions(+), 11 deletions(-)

diff --git a/CONSTRAINTS.md b/CONSTRAINTS.md
index d028690..4c0d286 100644
--- a/CONSTRAINTS.md
+++ b/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):
-- We are using **one base template** (`AGENT_TEMPLATE_VMID`) by design.
-- In current workflow, updating zlh-agent implies building + copying binary into the template container:
-  - **agent change == template promotion**
-- Prefer API-side wire compatibility fixes over agent/template changes unless we intentionally schedule a template rev.
+## Execution model constraints
+- zlh-agent executes installer logic as **embedded scripts**.
+- Embedded scripts must not rely on filesystem-relative paths (`$0`, `dirname`, etc.).
+- Any shared logic must be executed in the **same shell session** as its callers.
+
+---
+
+## 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
+
+---