feat: add optional Semantic Guard plugin for variable-level alignment…

[Fengrru]

What

This adds a semantic guard that checks whether two LLM-generated principles actually mean the same thing by the same variable names, before PiEvo throws them into the same Bayesian pot.

Why

Say PiEvo is working on combustion. The Principle Agent generates two candidates:

"Metals contain phlogiston. When burned, phlogiston escapes. Mass remains constant."

"Metals combine with oxygen to form oxides. Mass increases."

Both mention mass_change. PiEvo's Bayesian update treats them as sharing an observational vocabulary, so it computes likelihoods as if they're talking about the same quantity. They're not. Phlogiston's mass_change means "weight of dephlogisticated metal in open air." Oxidation's means "weight of metal oxide in sealed vessel." Same name, different referent, different measurement protocol — the posterior gets corrupted.

This isn't an edge case. It's the Phlogiston → Oxidation paradigm shift, and it also occurs with Caloric → Kinetic (temperature as primitive measurement vs. derived quantity).

How

The hook sits at exactly one place: update_pievo_state(), between _extract_principles() and _handle_new_principles(). A new principle is checked against every existing one. If any shared variable name maps to a different referent, operational definition, or evidential status, that principle is removed from self.principles and never reaches the GP training or posterior update.

When guard is None (the default), nothing changes.

_extract_principles()
       │
       ▼
  [guard hook] ── blocked principles removed
       │
       ▼
_handle_new_principles()   ← only validated principles

Files

New — pievo/guard/ (6 modules, no new dependencies)

• signature.py — data models
• alignment.py — 3D alignment vector (referential, operational, evidential; EXACT / TOKEN / EMBEDDING)
• policy.py — StrictPolicy, PermissivePolicy, ConservativePolicy
• extractor.py — LLM extraction via PiEvo's existing util_client, plus ManualExtractor for ablation; 4 few-shot examples
• guard.py — SemanticGuard orchestrator
• __init__.py — public API

Modified (+83 lines, both additive)

• evolveflow.py — PiEvo.__init__ accepts optional guard parameter; hook in update_pievo_state()
• main.py — --enable-semantic-guard and --guard-policy CLI flags

Tests

tests/test_semantic_guard.py — 23 tests, all passing.

Six of them replicate the exact guard hook logic from update_pievo_state(): blocked principles removed, validated ones survive, mixed batches handled correctly, guard=None passes everything through.

py -m pytest tests/test_semantic_guard.py -v

Usage

pievo -t task.yaml -m model.yaml -o ./out \
  --enable-semantic-guard --guard-policy strict

• strict — any misalignment → block (default)
• permissive — partial operational alignment → restrict
• conservative — uncertain extraction → abstain