scripts/spec_guard.py

#!/usr/bin/env python3
"""Small deterministic validation for Imago visual brief and evidence JSON. No image model calls."""
import json, sys, pathlib

VALID_STATES={'passed','failed','not_tested'}

def review(spec):
    errors=[]
    if not isinstance(spec,dict): return ['spec must be a JSON object']
    task=spec.get('task')
    if task not in {'create','edit','data_visual','factual_visual','ui_mockup','prompt_only'}:
        errors.append('task must be create/edit/data_visual/factual_visual/ui_mockup/prompt_only')
    if not isinstance(spec.get('requested_output'),str) or not spec['requested_output'].strip():
        errors.append('requested_output must be a nonblank string')
    if task=='edit' and not spec.get('source_present',False):
        errors.append('edit requires an accessible source image')
    if task=='edit' and not (isinstance(spec.get('preserve'),list) and spec['preserve']):
        errors.append('edit must specify preservation constraints')
    if task in {'data_visual','factual_visual'}:
        if not isinstance(spec.get('claims'),list) or not spec['claims']:
            errors.append('factual/data visual requires source-grounded claims')
        else:
            for idx,c in enumerate(spec['claims']):
                if not isinstance(c,dict) or not c.get('source') or not c.get('text') or c.get('verified') is not True:
                    errors.append('claim %s is not supported by a verified source' % idx)
    if spec.get('claimed_rendered') is True and spec.get('render_tool_result') not in {'success'}:
        errors.append('cannot claim rendered visual without a successful tool result')
    for gate,state in (spec.get('qa') or {}).items():
        if state not in VALID_STATES: errors.append('invalid QA state for '+str(gate))
        if state=='failed' and spec.get('ready') is True: errors.append('failed QA gate blocks ready: '+str(gate))
    if spec.get('ready') is True and any(x=='not_tested' for x in (spec.get('qa') or {}).values()):
        errors.append('cannot mark ready when required QA evidence is not tested')
    if task=='prompt_only' and spec.get('claimed_rendered') is True:
        errors.append('prompt-only request cannot automatically claim image rendered')
    return errors

if __name__=='__main__':
    if len(sys.argv)!=2:
        print('Usage: python scripts/spec_guard.py visual-spec.json');sys.exit(2)
    obj=json.loads(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8'))
    findings=review(obj)
    print(json.dumps({'passed':not findings,'findings':findings},indent=2))
    sys.exit(1 if findings else 0)