README: surface verify-before-mutate doctrine, field trust levels, verify-before-fix pattern
- New 'Operating Doctrine (read first)' section with the .117 rule, safe-mutate wrapper usage, field trust taxonomy, and contract-native verify-before-fix flow - Added hermes-key-enforcement to templates table - Added stirling-pdf-agent-access to functions table - Noted VERIFY-BEFORE-USE labels on infrastructure-control
This commit is contained in:
Abiba
@@ -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 <verifier> # e.g. zulip-platform-verification → verdict
|
||||
prose lint <fixer> # validate structure without executing
|
||||
prose preflight <fixer> # check deps/env, no execute
|
||||
prose run <fixer> # 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/`)
|
||||
|
||||
Reference in New Issue
Block a user