Skip to main content
Status: draft v0.1 — body sourced from TriGraph spec entity. Docs-mirror file added by docs lane to surface ratified specs that lacked an on-disk mirror.

​
SPEC-088: Agent Preflight Discipline and Reflexive Rule Gates

​
SPEC-088 v0.1 — Agent Preflight Discipline and Reflexive Rule Gates

Status: draft for immediate Frank/Samantha/Donna review Author: Candi, governance/methodology Origin: Frank mandate captured by Samantha in journal #82, signal f6812482-8ff9-49f3-8f0b-ef7c916652ca Related: SPEC-085, SPEC-063, SPEC-078, SPEC-081, SPEC-059, SPEC-060, ADR #52

​
Summary

This SPEC turns four recurring agent anti-patterns into explicit operating discipline:
  1. doc-skip
  2. memory-skip
  3. brute-force hacking / diagnostic bypass
  4. asking permission instead of acting
The point is not more ceremony. The point is to make agents stop burning operator time, money, and trust by skipping the context that already exists or by probing around a missing source of truth.

​
Problem

Journal #82 records a concrete failure chain from Samantha’s Render session:
  • Render/Neo4j plan sizing was copied from stale or adjacent context instead of checked against current vendor docs.
  • Existing memory and resume notes already pointed to relevant context, including the Render API key path and sizing feedback, but were not applied before action.
  • Black-box edge probing substituted for direct Render API inventory.
  • The agent asked whether to file a postmortem even though postmortem-on-error was already an unconditional rule.
These failures are expensive because they create follow-on PRs, operator idle time, wrong confidence, and hidden state drift.

​
Taxonomy

The parent failure is preflight-skip: acting before checking the minimum source that should govern the action.

​
A. Doc-Skip

Definition: The agent relies on training memory, neighboring examples, or inferred vendor behavior when a primary source exists and the action depends on a current external fact. Applies before:
  • vendor/cloud/IaC mutations
  • plan/tier/limit/cost/resource sizing choices
  • API/SDK/protocol/version-sensitive work
  • auth/OAuth/security configuration
  • generated deployment files such as Render Blueprints, Terraform, Helm, Docker Compose, GitHub Actions, or Cloudflare config
Rule: 
Before production-state mutation or IaC authoring that depends on external current behavior, check the primary vendor/API docs and cite the source in the artifact, signal, journal, PR, or session delta.
Minimum acceptable check:
  • official docs, API schema, CLI help, or live provider API inventory
  • current date-aware where the fact can change
  • citation or explicit note of what was checked

​
B. Memory-Skip

Definition: The agent fails to query Prism memory, resume notes, journals, or recent feedback before an action that is historical, architectural, previously-postmortemed, or project-specific. Applies before:
  • continuing a resumed lane
  • touching a surface with known postmortems
  • changing cloud/deploy/install/signaling/memory/governance behavior
  • asking the operator for a fact likely to exist in handoff, secrets notes, journal, or memory
  • repeating a diagnosis path already tried in prior sessions
Rule: 
Before project-specific or previously-postmortemed work, run targeted Prism recall and read the top applicable handoff/feedback result before acting.
For cloud/deploy/install production work, the recall query must include the action surface and the risky field, for example Render plan tier, Neo4j sizing, OAuth redirect, API key path, or Blueprint pserv port.

​
C. Diagnostic Bypass / Brute-Force Hacking

Definition: The agent keeps probing, retrying, renaming, or changing parameters after a direct source of truth exists or after the real blocker is access/info rather than implementation. Rules: 
Black-box probing is allowed for confirmation. It is not allowed as the primary diagnostic when an API, CLI, SDK, logs, database, source file, or official status surface exists.

After two failed probes of the same unknown with varied parameters, stop before the third and identify the missing source of truth, credential, API, log, or doc. Then acquire or surface that gap.

Do not rename formats, swap delimiters, alter ports, bump plans, or rewrite config cosmetically unless the root cause has been identified and cited.

​
D. Permission Reflex

Definition: The agent asks whether to do a mandatory or clearly assigned action instead of doing it. Rules: 
Unconditional methodology triggers are actions, not questions.
Unconditional triggers include:
  • file a postmortem for every detected error
  • ACK and act on non-empty signal drains
  • checkpoint or wrap at lifecycle close
  • record a journal/delta when handing off substantive work
  • update TODOs when work is completed or new work is discovered
  • signal the correct lane owner when a cross-lane answer is needed
Default posture: 
Narrate and act. Ask only when the action is ambiguous, hard to reverse, invisible to peers, outside assigned authority, or explicitly gated by an ask-first rule.

​
Risk Tiers

Low risk:
  • read-only file inspection
  • local tests
  • formatting or docs copy that does not alter doctrine
Expected discipline: memory check when historical/project-specific; docs check only if external current facts are used. Medium risk:
  • code changes to shared behavior
  • MCP verb behavior
  • dashboard behavior
  • docs/spec changes with methodology impact
Expected discipline: targeted memory recall, relevant SPEC/ADR read, tests or explicit verification. High risk:
  • production-state mutation
  • cloud/vendor resource provisioning
  • security/auth/OAuth/secrets changes
  • governance/authority changes
  • deploy/install path changes
  • multi-agent coordination/routing changes
Expected discipline: targeted memory recall, current official doc/API check, explicit root cause, verification plan, and journal/delta capture.

​
Reflexive Enforcement Design

Phase 0 is normative text only. Phase 1+ adds guardrails.

​
Phase 1 — Prompt and BIOS Surface

Add a compact rule block to BIOS/methodology surfaces:
  • external-current fact -> docs/API first
  • project/historical fact -> Prism memory first
  • two failed probes -> stop and identify missing source of truth
  • unconditional methodology trigger -> do it, do not ask

​
Phase 2 — Pre-Tool Self-Check

Add an agent-side checklist/method fragment that fires before high-risk tools or production mutations: 
{
  "risk_tier": "high",
  "action_surface": "render|oauth|install|governance|signal|memory|deploy",
  "memory_checked": true,
  "docs_or_api_checked": true,
  "root_cause_named": true,
  "verification_plan_named": true
}
This can begin as a method fragment and later compile into Agent Contracts.

​
Phase 3 — Telemetry and Warnings

Ring 5 records and surfaces:
  • actions taken after no recent recall in high-risk contexts
  • repeated probe loops
  • want me to / should I permission-reflex language before unconditional actions
  • postmortems that cite doc-skip or memory-skip
  • operator corrections from SPEC-060 once prism_operator_input lands
Warnings are non-blocking at first.

​
Phase 4 — Contract Integration

Agent Role Contracts include preflight obligations by role and risk tier. Repeated violations affect role-binding standing per SPEC-085, not the canonical role globally.

​
Immediate Rule Additions

These rules are effective as governance guidance immediately on SPEC creation, pending ratification into templates/Agent Contracts:
  1. Docs-before-current-external-facts: If a fact can change outside the repo and controls a production/cloud/API/IaC decision, check the official source before acting.
  2. Memory-before-project-history: If the question is how Prism has handled something before, or a surface has recent postmortems, query Prism memory before git/SQL/probing.
  3. Two-probe stop: More than two failed probes of the same unknown requires naming the missing source of truth before continuing.
  4. API-over-edge: Provider API/CLI/logs beat black-box edge checks for provider state. Edge checks confirm symptoms only.
  5. Postmortems-first: Every detected error gets a postmortem; never ask permission to file one.
  6. Do-not-ask-for-mandated-actions: If the queue, signal, methodology, or operator mandate clearly assigns the next action, execute and report.
  7. Root-cause-before-cosmetic-change: Do not rename formats, swap delimiters, or tweak configs as experiments without a named root cause.
  8. Cite-the-preflight: High-risk session deltas, journals, PRs, or signals must name the doc/API/memory source used for the preflight.

​
Acceptance Criteria

  1. ADR #52 records the SPEC-vehicle decision.
  2. SPEC-088 exists as the durable vehicle.
  3. Immediate rules are captured as memory for current agents.
  4. TODOs exist for BIOS/method-fragment update, telemetry hook design, and Agent Contract integration.
  5. Samantha receives TaskCompleted/StatusUpdate with the rule set and vehicle decision.
  6. Frank receives a concise report of what changed and what remains to implement.

​
Open Implementation Work

  • Add a method fragment for high-risk preflight checks.
  • Add BIOS/template wording during the next governed template sweep.
  • Add telemetry rules for two-probe loops and permission-reflex phrases.
  • Fold preflight obligations into Agent Role Contracts when that SPEC lands.
  • Consider dashboard panels: doc-skip incidents, memory-skip incidents, repeated-probe loops, permission-reflex corrections.

​
References

  • Journal #82 b71b5fd3-b031-4034-86cc-763146005d0b
  • SPEC-085 Constitutional Governance Vocabulary and Rights Model
  • SPEC-063 Postmortem + Retrospective Discipline
  • SPEC-060 Operator-Experience Memory Capture
  • SPEC-059 Tri-Graph Memory Activation
  • SPEC-081 Structured Large Payload Pattern
  • feedback_memory_first_for_historical
  • feedback_postmortem_on_every_error
  • feedback_continue_through_milestones
  • feedback_size_for_full_capability
Last modified on May 9, 2026