PlanResult JSON deep dive: fields, risk, jq recipes, and what is never stored

The intent compiler bet only works if the artifact is boring and stable. PlanResult is that artifact: one JSON document on stdout when you pass --output json, human UI on stderr, no manifests, no API keys. This post is the field guide to the schema — companion to the pipeline patterns in Kubernetes in CI/CD: gating cluster changes with plan JSON before apply and the CI / JSON docs.

Emit it

kprompt "scale api to 10" -n prod --output json
kprompt "scale api to 10" -n prod -o json > plan.json

Envelope fields

{
  "apiVersion": "kprompt.io/v1",
  "kind": "PlanResult",
  "schemaVersion": "1",
  "prompt": "scale api to 10",
  "cluster_context": "kind-staging",
  "plan": {
    "intent": "scale",
    "summary": "Scale Deployment/api to 10 replicas",
    "requiresApproval": true,
    "namespace": "prod",
    "actions": [
      {
        "op": "scale",
        "backend": "kubernetes",
        "kind": "Deployment",
        "name": "api",
        "namespace": "prod",
        "replicas": 10
      }
    ]
  },
  "risk": { "level": "medium", "denied": false, "message": "Mutation requires approval" },
  "applied": false
}

plan.actions — what CI should inspect

• op — scale, deploy, delete, patch, rollback, …
• backend — kubernetes, helm, …
• kind / name / namespace — target object
• cluster_context — set on multi-context paths
• replicas / revision — when relevant
• diff — optional live before→after text (still not a full manifest dump)

Actions are intentionally thin. Policy engines gate on op + kind + namespace, not on guessing YAML from an LLM.

risk — the gate that matters

# Hard deny must fail the job
jq -e '.risk.denied == false'

# Block deletes
jq -e '[.plan.actions[].op] | index("delete") | not'

# Allow only scale
jq -e '.plan.intent == "scale"'

# Reject high risk
jq -e '.risk.level != "high" and .risk.level != "denied"'

# Namespace allow-list
jq -e '.plan.namespace == "staging"'

result — read and report payloads

For get/list/explain/logs/optimize/graph and similar reads, result holds a structured payload (shape depends on intent). Mutating plans that only print a plan leave result empty or omitted. Optimize attaches idle / rightsizing / findings under result — see optimize my cluster.

Related kinds: RouteResult and MultiContextResult

• RouteResult — multi-tool chain: steps[] of PlanResult, aggregate risk, stoppedAt / stopReason
• MultiContextResult — read fan-out across contexts: contexts[], steps[], optional fleetSummary for optimize

Gate RouteResult by inspecting .risk and each .steps[].risk.denied. Never treat a parent --approve as consent for every step without reading the aggregate plan.

History vs CI artifacts

What is never stored

• LLM API keys
• Full Kubernetes manifests / Secret data
• kubeconfig files or tokens
• Raw provider request dumps in PlanResult

Anti-patterns

• One CI step: -o json --approve on production
• Parsing risk.message with regex instead of risk.denied / level
• Assuming schemaVersion will stay "1" forever without checking
• Committing plan.json that you manually edited to bypass gates

Wire it

#!/usr/bin/env bash
set -euo pipefail
json="$(kprompt "scale api to 3" -n staging -o json)"
echo "$json" | jq -e '.risk.denied == false' >/dev/null
echo "$json" | jq -e '.plan.intent == "scale"' >/dev/null
echo "$json" > plan.json
# Human or second job:
# kprompt "scale api to 3" -n staging --approve --wait

Full GitHub Actions patterns live in the CI gates post. For why this artifact beats a chat transcript, see the intent compiler note. Schema reference stays mirrored on CI / JSON docs.