grounding checkpoints

---

title: Grounding Checkpoints category: concepts tags: [harness, execution, drift-detection, layer-3, quality] status: developing created: 2026-04-28 updated: 2026-04-28 sources:

• "harness-implementation-plan" related:
• "agentic-harness"
• "structured-planning"
• "adversarial-verification"
• "spec-hardening" layer: "Layer_3" summary: Layer 3 enforces smallest verifiable changes with mandatory re-grounding against the spec. Drift detection prevents scope creep — if the spec changed, execution stops and replanning occurs. provenance: extracted: 0.85 inferred: 0.15 ambiguous: 0.0

---

Grounding Checkpoints (MVC Execution)

Origin Principle

Smallest verifiable change + mandatory re-grounding against spec. Drift is detected, not assumed away.

Flow

For each ready node in plan:
    ↓
    ┌─ PRE-EXECUTION GROUNDING ──────────────────────────┐
    │ 1. Load HardenedSpec                                │
    │ 2. Compare spec_version vs last checkpoint          │
    │ 3. If spec changed: drift_detected → abort, replan │
    │ 4. Compute state_hash = hash(all node statuses)     │
    │ 5. Record GroundingCheckpoint                       │
    └─────────────────────────────────────────────────────┘
    ↓
    Execute subtask (agent performs code change)
    ↓
    ┌─ POST-EXECUTION GROUNDING ─────────────────────────┐
    │ 1. Re-read HardenedSpec                             │
    │ 2. Verify output matches declared outputs           │
    │ 3. Verify no anti-criteria violated                 │
    │ 4. Git commit intermediate state                    │
    │ 5. Record GroundingCheckpoint                      │
    └─────────────────────────────────────────────────────┘
    ↓
    Emit: subtask_completed → Layer 4 (Automated QA)

GroundingCheckpoint Data Contract

Each checkpoint captures:

• task_id — which task
• timestamp — when the checkpoint was taken
• spec_id and spec_version_at_checkpoint — what spec was current
• drift_detected — boolean; if true, execution halts
• drift_details — what changed if drift detected
• state_hash — hash of all node statuses for integrity
• committed — whether the checkpoint was committed
• git_sha — the commit hash for intermediate state

Drift Detection

If the spec changes between checkpoints (version number differs), execution aborts and replanning is triggered from structured-planning. This prevents agents from working against stale specs.

Anti-criteria verification is also checked at post-execution: if any forbidden behavior occurred, the subtask is marked failed.

Error States

Error	Recovery
spec_drift	Abort current task, emit drift_detected, replan from Layer 2
anti_criteria_violation	Mark subtask failed, retry or abort
grounding_checkpoint_failure	Log warning, continue without drift check (degraded)
all_nodes_failed	Emit execution_complete with failure state, store failure pattern

Config

{
  "execution": {
    "grounding_interval": "every_subtask",
    "grounding_n": 1
  }
}

grounding_interval: every_subtask (safest) or every_n_subtasks. Correctness > speed.

Extension Interface

Type	Name	Description
Tool	execute-next-task	Execute next plan node with grounding
Tool	grounding-check	Manual grounding checkpoint
Command	/harness-execution-status	Current execution state

Files

• lib/harness-executor.ts — Executor class, grounding logic, drift detection
• extensions/harness-executor.ts — Extension: manages subtask execution, grounding hooks