diff --git a/README.md b/README.md index 24a9ad6..e4b1fc0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,70 @@ Operating contracts for Syslog agents. Each `.prose.md` file defines a **function** (callable helper), **responsibility** (recurring duty with state), or **pattern** (instantiable knowledge/template) that agents can execute via OpenProse or follow manually. +## ⚠️ Operating Doctrine — Read Before Acting + +Two rules govern how agents interact with this repo and the infrastructure it +describes. Internalize both before running or relying on any contract. + +### 1. Verify-before-mutate (the `.117` rule) + +**Contracts are leads to investigate, NOT facts to act on.** Live-state fields +(IPs, ports, hostnames, credentials, container names, PIDs) drift. Before any +mutating operation on infrastructure, verify the current state against the live +system. On drift, halt and ask the user which value is correct — do NOT "fix" +the live state to match a stale contract. + +Origin: a contract stated Zulip CT 117 was at `.117`; the live IP was `.19`. +An agent ran `pct set` without checking `pct config` first and changed the IP +to the wrong value, breaking Zulip. The staleness was harmless until acted on. + +**Layer 3 enforcement — the `safe-mutate` wrapper** (deployed on all 5 agents: +Abiba, Tanko, Mumuni, Koby, Koonimo). ALL infrastructure mutations MUST go +through `safe-mutate`. Raw `sed -i`, `pct set`, `docker compose up +--force-recreate`, `kill`, `rm` on infrastructure outside `safe-mutate` is an +auditable protocol violation. The wrapper runs a verify command, optionally +checks an `--expect` pattern, refuses on mismatch, and logs every call to +`/root/.safe-mutate/audit.log`. + +``` +safe-mutate --verify "CMD" [--expect "PATTERN"] --mutate "CMD" [--reason "WHY"] +safe-mutate --verify "CMD" --dry-run --mutate "CMD" # verify + show, no execute +safe-mutate --verify "CMD" --verify-only # record a verification only +``` + +Load the `verify-before-mutate` skill (local pi skill + RA-H shared) for the +full protocol. See knowledge graph node #604 for the post-mortem. + +### 2. Field trust levels + +Not all contract content carries the same trust: + +| Field type | Trust level | Examples | +|-----------|-------------|----------| +| **Policy** | Authoritative — trust the contract | "hardcoded harness keys forbidden", "use api_key_env" | +| **Live state** | **Never trust — always verify** | IPs, ports, hostnames, credentials, container names, PIDs | +| **Procedure** | Trust but adapt | command patterns are right, values may be stale | + +Contracts label live-state fields with `VERIFY-BEFORE-USE`. Treat any such +field as a hint to confirm against the live system, not a fact to apply. + +### 3. Verify-before-fix (contract-native) + +Never `prose run` a fix-contract directly. Run its verifier first, read the +verdict, lint the fixer, then run: + +``` +prose run # e.g. zulip-platform-verification → verdict +prose lint # validate structure without executing +prose preflight # check deps/env, no execute +prose run # only after verdict + lint pass +``` + +`kind: responsibility` contracts VERIFY and return a verdict without making +changes. `kind: function` contracts DO things. Forme `### Requires` → +`### Maintains` wiring enforces this at the DAG level: a fixer that requires a +fresh verdict cannot fire until the verifier has run. + ## How Agents Run These Contracts ### Option A: Via OpenProse CLI (preferred) @@ -63,7 +127,8 @@ Generate configs or perform a transformation on demand. No persistent state. | Contract | Description | Key Parameters | |---|---|---| -| `hermes-config-template` | Standard Hermes config for any Syslog agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM). | `agent_name` (required), `default_model`, `auxiliary_model` | +| `hermes-config-template` | Standard Hermes config for any Syslog agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM) + standardized `api_key_env` key indirection. | `agent_name` (required), `default_model`, `auxiliary_model` | +| `hermes-key-enforcement` | **Enforcement contract** — all harness/LiteLLM providers MUST use `api_key_env`, never hardcoded keys. Includes detection query, rotation procedure, violation response. External providers (DeepSeek, OpenAI) exempt. | (none — doctrine reference) | ### Reference Documents (`kind: pattern` — read for context, not run) @@ -71,7 +136,7 @@ Encode topology, architectural decisions, and lessons. You read them before plan | Contract | Description | |---|---| -| `infrastructure-control` | Full topology and control pattern: 5-node Proxmox cluster, 3 Docker ecosystems, NFS storage, network verification, IP-first configuration doctrine. | +| `infrastructure-control` | Full topology and control pattern: 5-node Proxmox cluster, 3 Docker ecosystems, NFS storage, network verification, IP-first configuration doctrine. Live-state fields marked `VERIFY-BEFORE-USE`. | | `pi-approval-architecture` | pi's approval model vs Hermes, available commands, architectural constraints. | | `zulip-adapter-lessons` | Failure modes, fixes, and patterns from building the pi Zulip extension and Hermes Zulip plugin. | @@ -83,6 +148,7 @@ Called on-demand as single-render tools. |---|---| | `litellm-health` | Verifies LiteLLM inference stack health: containers, router, GPU fleet, model inference, agent keys. | | `infrastructure-monitoring` | Deploys Prometheus + GPU exporters + Grafana to monitor the inference fleet from CT 116. | +| `stirling-pdf-agent-access` | Documents the Stirling-PDF API access pattern for agents — global API key, 12 operations, curl examples. Agents use the `stirling-pdf-api` shared skill for templates. | | `hello-world` | Minimal test contract — verifies the OpenProse execution pipeline works. | ### Scripts (`scripts/`)