Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.
"""Optional knowledge boundaries: retrieval, relationships, provenance and packaging."""
import copy
import json
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'scripts'))
sys.path.insert(0, str(ROOT / 'skills/3dviz-pro-max/scripts'))
from catalog import load_catalog as installed_catalog
from catalog_validation import ContractError, load_catalog, validate_knowledge
from evidence_validation import CANONICAL, content_hash, validate_event
from manifest_contract import KNOWLEDGE_KINDS
from search import search
class KnowledgeTests(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.addCleanup(self.tmp.cleanup)
self.root = Path(self.tmp.name)
self.skill = self.root / 'skills/3dviz-pro-max'
shutil.copytree(ROOT / 'skills/3dviz-pro-max', self.skill,
ignore=shutil.ignore_patterns('__pycache__'))
self.data = self.skill / 'data'
manifest = json.loads((self.data / 'manifest.json').read_text())
# A catalog without optional knowledge must not retain recipes that reference it.
seed = next(row for row in installed_catalog(self.skill, 'recipes')[1]
if row['id'] == 'recipe.linear-transformation-3d')
seed.pop('_path', None)
# These fixtures exercise supported legacy catalogs with array shards.
manifest.pop('layout_version', None)
self.recipe_path = self.data / 'recipes/test-recipes.json'
self.recipe_path.write_text(json.dumps([seed]))
manifest['collections']['recipes'] = 'recipes/test-recipes.json'
manifest['collections'].pop('knowledge', None)
(self.data / 'manifest.json').write_text(json.dumps(manifest))
self.recipes, self.sources, self.directions = load_catalog(self.root)
self.record = copy.deepcopy(self.recipes['recipe.linear-transformation-3d'])
self.record.update(id='knowledge.test-material', knowledge_kind='material-profile',
title={'en': 'Sentinel material'}, aliases={'en': ['uniqueknowledgefixtureterm']},
content={key: ['An observable statement.'] for key in
('principles', 'implementation', 'observable_checks')},
related_ids=['recipe.linear-transformation-3d'])
for index, claim in enumerate(self.record['claims']):
claim['id'] = f'claim.knowledge-sentinel-{index}'
def install_knowledge(self):
path = self.data / 'knowledge'
if path.exists():
shutil.rmtree(path)
path.mkdir()
(path / 'test.json').write_text(json.dumps([self.record]))
manifest = json.loads((self.data / 'manifest.json').read_text())
manifest['collections']['knowledge'] = 'knowledge/*.json'
(self.data / 'manifest.json').write_text(json.dumps(manifest))
def test_optional_collection_preserves_recipe_callers(self):
self.assertEqual(installed_catalog(self.skill, 'knowledge')[1], [])
self.assertEqual(load_catalog(self.root, 'knowledge')[0], {})
self.install_knowledge()
self.assertEqual(set(load_catalog(self.root)[0]), set(self.recipes))
self.assertEqual(len(installed_catalog(self.skill)[1]), len(self.recipes))
self.assertEqual(len(installed_catalog(self.skill, 'all')[1]), len(self.recipes) + 1)
linked_recipe = copy.deepcopy(self.recipes['recipe.linear-transformation-3d'])
linked_recipe['related_ids'] = [self.record['id']]
self.recipe_path.write_text(json.dumps([linked_recipe]))
self.assertEqual(set(load_catalog(self.root)[0]), set(self.recipes))
manifest = json.loads((self.data / 'manifest.json').read_text())
manifest['collections'].pop('knowledge')
(self.data / 'manifest.json').write_text(json.dumps(manifest))
with self.assertRaisesRegex(ContractError, 'unknown related record'):
load_catalog(self.root)
def test_family_content_and_source_boundaries(self):
for kind in KNOWLEDGE_KINDS:
self.record['knowledge_kind'] = kind
self.record.update(applies_when=['The relevant model is selected.'],
constraint_level='advisory', check_method='state')
validate_knowledge(self.record, self.sources, self.directions)
for field, value, message in [('knowledge_kind', 'unknown', 'knowledge_kind'),
('content', {'principles': []}, 'nonempty')]:
changed = {**self.record, field: value}
with self.assertRaisesRegex(ContractError, message):
validate_knowledge(changed, self.sources, self.directions)
self.record['claims'][0]['source_refs'][0]['source_id'] = 'source.missing'
with self.assertRaisesRegex(ContractError, 'unknown source'):
validate_knowledge(self.record, self.sources, self.directions)
def test_reasoning_and_domain_checks_need_applicability_and_method(self):
for kind, field, value in [('reasoning-rule', 'constraint_level', 'advisory'),
('domain-validation', 'check_method', 'analytic')]:
row = {**self.record, 'knowledge_kind': kind, 'applies_when': ['A bounded model is used.']}
with self.assertRaisesRegex(ContractError, field):
validate_knowledge(row, self.sources, self.directions)
row[field] = value
validate_knowledge(row, self.sources, self.directions)
row['applies_when'] = []
with self.assertRaisesRegex(ContractError, 'nonempty'):
validate_knowledge(row, self.sources, self.directions)
def test_dangling_relationship_and_global_claim_collision(self):
self.record['related_ids'] = ['knowledge.missing']
self.install_knowledge()
with self.assertRaisesRegex(ContractError, 'unknown related record'):
load_catalog(self.root)
self.record['related_ids'] = []
self.record['claims'][0]['id'] = self.recipes['recipe.linear-transformation-3d']['claims'][0]['id']
self.install_knowledge()
with self.assertRaisesRegex(ContractError, 'duplicate global claim'):
load_catalog(self.root)
def test_search_filter_hash_source_lookup_and_installed_cli(self):
self.install_knowledge()
manifest, records, sources = installed_catalog(self.skill, 'all')
self.assertEqual(search('uniqueknowledgefixtureterm', manifest, records)['results'], [])
result = search('uniqueknowledgefixtureterm', manifest, records, collection='knowledge', kind='material-profile')
found = result['results'][0]
self.assertEqual((found['id'], found['collection'], found['kind']),
(self.record['id'], 'knowledge', 'material-profile'))
self.assertEqual(search('uniqueknowledgefixtureterm', manifest, records, collection='all',
kind='tool-adapter')['results'], [])
source_ids = {s['id'] for s in sources}
self.assertTrue(all(ref['source_id'] in source_ids for c in self.record['claims']
for ref in c['source_refs']))
changed = copy.deepcopy(records)
changed[-1]['content']['principles'].append('Changed guidance.')
self.assertNotEqual(result['catalog_hash'], search('uniqueknowledgefixtureterm', manifest, changed,
collection='knowledge')['catalog_hash'])
output = subprocess.check_output([sys.executable, str(self.skill / 'scripts/search.py'),
'uniqueknowledgefixtureterm', '--collection', 'knowledge',
'--kind', 'material-profile'], cwd=self.root, text=True)
self.assertEqual(json.loads(output)['results'][0]['id'], self.record['id'])
def test_knowledge_evidence_hash_claim_and_collection(self):
records = {**self.recipes, self.record['id']: self.record}
event = {'schema_version': 1, 'event_id': 'test-knowledge', 'change_id': 'test',
'timestamp': '2026-09-07T00:00:00Z', 'summary': 'Curate reusable knowledge.',
'actor': {'kind': 'agent', 'name': 'test'}, 'event_type': 'change-proposed',
'record_refs': [{'collection': 'knowledge', 'record_id': self.record['id'],
'revision': self.record['revision']}],
'payload': {'before_hash': None, 'after_hash': content_hash(self.record),
'hash_algorithm': 'sha256', 'canonicalization': CANONICAL}}
validate_event(event, records, self.sources, self.root, 'test')
event['payload']['after_hash'] = '0' * 64
with self.assertRaisesRegex(ContractError, 'content mismatch'):
validate_event(event, records, self.sources, self.root, 'test')
claim = self.record['claims'][0]
event.update(event_type='source-read', payload={
'source_id': claim['source_refs'][0]['source_id'], 'locator': 'Selected section',
'source_version': 'Accessed source', 'accessed_at': '2026-09-07',
'supported_claim_ids': [claim['id']]})
validate_event(event, records, self.sources, self.root, 'test')
event['record_refs'][0]['collection'] = 'recipes'
with self.assertRaisesRegex(ContractError, 'collection does not match'):
validate_event(event, records, self.sources, self.root, 'test')
if __name__ == '__main__':
unittest.main()