Planner Context Window and Prompts

Iris (our OpenClaw AI agent) does not plan from a generic greenhouse prompt. Every planning event gets a generated context window that describes the current room, the active plan, recent outcomes, forecast pressure, crop targets, equipment state, lessons, and data-health caveats.

The context window is built before OpenClaw receives the event. OpenClaw routes the message; MCP tools validate writes; the ESP32 enforces the physical state machine.

Dynamic Data Window

scripts/gather-plan-context.sh builds the live greenhouse packet. It reads TimescaleDB views, Home Assistant state where needed, and current ESP32/forecast data. The packet is plain text because it has to be robust under both local and cloud planner routes.

Current sections include:

Section	What Iris gets	Planning use
System health	Data-health and dependency completeness	Decides whether to trust inputs or degrade.
Active plan	Future transitions and Tier 1 values	Prevents stale or contradictory posture.
Zone conditions	Temp, RH, VPD, CO2, outdoor weather, water, enthalpy	Diagnoses current stress and zone imbalance.
ESP32 state	Current firmware state if available	Distinguishes plan intent from real controller mode.
24h hourly pattern	Temperature, VPD, RH, CO2, lux	Shows what just happened before forecast reasoning.
Planner scorecard	Today’s score and recent trend	Connects decisions to measured outcomes.
Compliance	24h zone band percentages	Separates temp and VPD failure modes.
DIF and DLI	Day/night differential and light estimates	Avoids overreacting to known sensor limitations.
Hydro and irrigation	Water quality, schedules, history	Keeps climate tactics aware of plant-water context.
Equipment runtime	Relay/equipment hours and transitions	Spots churn, stuck equipment, and cost drivers.
Energy and water	kWh, therms, watts, water trend	Makes cost/resource tradeoffs visible.
Crops and observations	Active crops and growing context	Keeps plan goals tied to plants, not abstract comfort.
Previous plan review	Governing plan, outcome fields, validation state	Forces the next plan to grade the last hypothesis.
Structured hypothesis	Typed predicted conditions and stress windows	Lets Iris compare forecast belief against actuals.
Tunable constraints	Firmware min/max/step readbacks	Prevents impossible or clamp-heavy writes.
Active lessons	Deduplicated high-value lessons	Carries durable learning into new decisions.
Current setpoints	Latest effective values	Fills unchanged waypoint values without broad queries.
Forecast alerts	Heat, VPD, frost, overcast, cold-front signals	Turns weather changes into tactical posture.
Context completeness	Reachability/staleness of dependencies	Makes missing data explicit.

Static Site Context

scripts/gather-static-context.sh also builds /srv/verdify/state/planner-static-context.md. It concatenates public Markdown pages from the site, excluding generated daily plans, dashboards, static assets, and scripts.

This gives Iris the greenhouse documentation in the same form launch readers see it:

structure, equipment, zones, crops, and known limits
safety architecture and data model
planning loop and AI-Writable Tunables
economics, evidence, and build notes
lessons and FAQ language that constrain public claims

Static context keeps the planner anchored to this greenhouse’s actual hardware and physical limitations.

Prompt Family

ingestor/iris_planner.py has a tailored prompt builder for each planning event:

Event	Purpose	Normal output
`SUNRISE`	Morning tactical plan for the next daylight and overnight period	Full `set_plan` with 3-6 compact transitions.
`SUNSET`	Overnight posture and cold/disease control	Full `set_plan` with nighttime transitions.
`MIDNIGHT`	Required full-plan audit path when scheduled	Full plan or validation-mode acknowledgement.
`TRANSITION`	Crop-band or solar transition checkpoint	`set_tunable` or `acknowledge_trigger`.
`FORECAST`	Weather delta review	Adjust posture only if forecast changed enough.
`DEVIATION`	Measured stress/deviation response	Immediate bounded correction or explanation.
`MANUAL`	Operator-requested ad hoc run	Whatever the operator asked, still within MCP bounds.

Each event gets the same safety contract, the same writable tunable limits, and the same audit headers. The difference is how much change the event is expected to make.

Prompt Contract

The stable prompt contract is public-safe to summarize:

READ: scorecard, climate, forecast, active plan, crop bands, lessons, alerts.
DIAGNOSE: identify the binding compliance axis and stress type.
DECIDE: apply safety first, then validated lessons, then forecast reasoning.
ACT: write bounded tunables or a full plan through MCP tools only.
REPORT: summarize decisions and tradeoffs for the operator.

The standing directives also require:

use MCP tools only
do not run shell, direct SQL, or Docker commands
include trigger_id and planner_instance on every write
do not acknowledge required SUNRISE/SUNSET full-plan cycles unless validation mode is active
call acknowledge_trigger for routine no-op cycles so SLA monitoring can close them honestly
write compact local plans and avoid broad read tools when using Gemma 4 26B A4B (MoE), served locally under the gemma4-26b alias

Context Window Trim Policy

The local route is designed for bounded, event-scoped context. Trigger-scoped sessions prevent chat history from growing without limit, but the generated packet still needs an explicit trim policy before required full plans move back to local by default.

Context class	Keep	Trim first
Safety and write contract	Firmware safety split, tunable bounds, audit headers, current setpoints	Never trim from required planning events.
Live state	Current climate, equipment state, active alerts, forecast pressure, active plan	Keep the latest compact rows; avoid broad historical dumps.
Recent outcomes	Last plan hypothesis, scorecard, stress windows, resource use	Keep concise summaries and links to plan/archive rows.
Lessons	Active curated lessons and high-confidence constraints	Collapse duplicate machine confirmations before local planning.
Static site context	Architecture, safety, known limits, crops/zones/equipment summaries	Prefer summaries and canonical links over full prose when local context is tight.
Long history	Old plans, raw extraction rows, full dashboard prose	Retrieve only when the event specifically needs it.

The practical rule is: local routine events should receive enough context to make a bounded tactical decision, not a full copy of the website and history. Heavyweight cloud reviews can carry more context, but they still use the same MCP write boundary.

Audit Header

Every delivered prompt ends with an audit banner:

trigger_id=<uuid>
planner_instance="local" | "opus"

The planner must pass those values into set_plan, set_tunable, or acknowledge_trigger. That is how Verdify correlates:

plan_delivery_log -> OpenClaw gateway delivery -> MCP write -> plan_journal/setpoint_changes -> public archive

If any link is missing, the failure should be visible. Missed cycles remain in the planning archive because planner availability is part of the system being audited.

Why This Matters

The AI layer can sound sophisticated, but the launch claim depends on a narrower fact: every planning decision is a bounded physical hypothesis with public evidence. The context window is what makes the hypothesis specific enough to test. The AI-Writable Tunables table is the schema. The ESP32 state machine is the enforcement layer. The scorecard is the judge.

🌱 Verdify