The Planning Loop

This page owns the planning workflow: how the AI planning agent receives context, writes a bounded plan, journals the hypothesis, and lets the dispatcher hand safe setpoints to the ESP32. It should not become the tunable catalog, the climate dashboard, or the safety page.

The exact runtime contract for triggers, payloads, accepted outputs, tunable writes, midnight review, and automatic site publishing lives on Planner Contract and AI Tunables.

At solar milestones, band transitions, forecast deltas, and deviation checks, the AI planning agent receives a structured greenhouse context window. The prompt carries a trigger ID, planner-instance stamp, MCP tool contract, current scorecard context, recent lessons, and the greenhouse state needed for that trigger.

Crop profiles define the target bands. The dispatcher derives the whole-house firmware band. The AI planning agent chooses bounded tactics inside that envelope. MCP validates the write. The ingestor dispatcher pushes changed values. The ESP32 firmware owns the physical relay state machine.

Live Planner State

The live panels here answer two narrow questions: is the planner healthy, and what plan is active now?

The Closed Loop

What The AI Planning Agent Reads

The planner assembles a bounded context packet rather than a generic prompt:

The crop target source lives on Crop Profiles. Current climate panels live on Climate Control.

Context Window And Prompts

The AI planning 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 the AI planning agent plans. 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 so the same context can move through both local and cloud planner routes.

Representative sections include:

Static Site Context

scripts/gather-static-context.sh 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. The planner context packet embeds that file with a SHA-256 digest, byte count, and line count, so the public site contract and the planner payload are tied to the same source tree.

Generated daily plan pages are handled by source records instead of copied HTML or Markdown. The site renders plan_journal, plan_delivery_log, setpoint-plan rows, scorecards, lessons, and daily summaries into /plans/YYYY-MM-DD; the planner receives those same records directly in the dynamic context packet.

This gives the AI planning agent the greenhouse documentation in the same form public readers see it:

• structure, equipment, zones, crops, and physical constraints
• safety architecture and data model
• planning loop and AI Tunables Traceability
• resource accounting, 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:

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. DEVIATION remains as a backward-compatible alias for old in-flight deliveries, but new trigger paths use FORECAST_DEVIATION.

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 MIDNIGHT/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 plans and avoid broad read tools during routine no-op or transition checks

Context Trim Policy

The planner 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 so required full plans stay focused.

The practical rule is: routine events should receive enough context to make a bounded tactical decision, not a full copy of the website and history. Larger 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 -> planner 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.

What The AI Planning Agent Writes

The AI planning agent writes tactical intent, not direct actuator commands. In production that means two MCP write paths:

The generated AI Tunables Traceability page owns the exact parameter names, bounds, defaults, current values, readbacks, and firmware references. This page intentionally does not duplicate that table.

Dispatch And Readback

The ingestor runs the setpoint dispatcher every 300 seconds, with an immediate reconciliation path after ESP32 reconnect. The dispatcher reads the active plan, resolves the latest applicable value for each parameter, compares it with current readbacks, and pushes only changed values through the ESPHome API. Final writes are logged in setpoint_changes; setpoint_snapshot stores the firmware cfg_* readbacks that confirm what the controller actually accepted.

Between dispatcher runs, the ESP32 keeps running locally from its current configured values. Failure behavior and relay ownership live on Safety Architecture.

Journal And Learning

Every plan is a hypothesis. plan_journal stores the plan ID, trigger metadata, hypothesis, experiment, expected outcome, conditions summary, and changed parameters. Later evaluation writes the outcome and score back to the same record.

Useful findings become rows in planner_lessons; they are not model self-modification. Future prompts can read validated lessons as ordinary database memory.

Planner outcome proof lives on the Scorecard. The generated lesson list lives on Lessons Learned.

Page Boundaries

Full dashboards: Controller ↗ · Planning ↗