blendops 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +74 -0
- package/LICENSE +21 -0
- package/README.md +208 -2
- package/bin/blendops.mjs +4 -0
- package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
- package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
- package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
- package/bundles/claude-desktop-manual/README.md +70 -0
- package/bundles/claude-desktop-manual/SKILL.md +62 -0
- package/bundles/claude-desktop-manual/manifest.json +278 -0
- package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
- package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
- package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
- package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
- package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
- package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
- package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
- package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
- package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
- package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
- package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
- package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
- package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
- package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
- package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
- package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
- package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
- package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
- package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
- package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
- package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
- package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
- package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
- package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
- package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
- package/bundles/generic-project-local/BLENDOPS.md +71 -0
- package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
- package/bundles/generic-project-local/README.md +73 -0
- package/bundles/generic-project-local/ROLLBACK.md +66 -0
- package/bundles/generic-project-local/manifest.json +66 -0
- package/bundles/skill-package/README.md +54 -0
- package/bundles/skill-package/blendops/LICENSE.txt +21 -0
- package/bundles/skill-package/blendops/SKILL.md +50 -0
- package/bundles/skill-package/blendops/agents/README.md +61 -0
- package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
- package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
- package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
- package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
- package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
- package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
- package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
- package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
- package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
- package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
- package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
- package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
- package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
- package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
- package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
- package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
- package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
- package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
- package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
- package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
- package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
- package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
- package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
- package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
- package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
- package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
- package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
- package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
- package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
- package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
- package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
- package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
- package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
- package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
- package/bundles/skill-package/blendops/references/skill-map.md +32 -0
- package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
- package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
- package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
- package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
- package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
- package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
- package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
- package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
- package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
- package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
- package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
- package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
- package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
- package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
- package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
- package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
- package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
- package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
- package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
- package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
- package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
- package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
- package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
- package/docs/README.md +276 -0
- package/docs/examples/glb-web-handoff/README.md +174 -0
- package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
- package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
- package/docs/knowledge-and-recipe-catalog.md +236 -0
- package/docs/recipes/README.md +27 -0
- package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
- package/docs/workflows/README.md +14 -0
- package/docs/workflows/full-non-blender-user-workflow.md +210 -0
- package/docs/workflows/product-hero-workflow.md +92 -0
- package/laws/README.md +32 -0
- package/laws/evidence-before-done.md +37 -0
- package/laws/no-arbitrary-python-interface.md +32 -0
- package/laws/non-blender-user-language.md +32 -0
- package/laws/official-runtime-only.md +78 -0
- package/package.json +103 -4
- package/packs/README.md +11 -0
- package/packs/product-hero-v0/PACK.md +114 -0
- package/registry/catalog-index.json +21344 -0
- package/registry/compatibility-matrix.json +533 -0
- package/registry/contract-context-fields.json +391 -0
- package/registry/knowledge-catalog.json +4648 -0
- package/registry/knowledge-sources.json +438 -0
- package/registry/recipe-catalog.json +2565 -0
- package/registry/runtime-capability-policy.json +525 -0
- package/registry/runtime-operations.json +4468 -0
- package/registry/skills.json +10231 -0
- package/registry/workflow-graph.json +7390 -0
- package/schemas/adapter-compatibility-matrix.schema.json +166 -0
- package/schemas/contract-context-fields.schema.json +147 -0
- package/schemas/execution-plan.schema.json +325 -0
- package/schemas/glb-web-handoff-manifest.schema.json +744 -0
- package/schemas/knowledge-record.schema.json +460 -0
- package/schemas/knowledge-source-registry.schema.json +268 -0
- package/schemas/operation-execution-ledger.schema.json +348 -0
- package/schemas/recipe-record.schema.json +469 -0
- package/schemas/runtime-capability-policy.schema.json +184 -0
- package/schemas/runtime-evidence-packet.schema.json +211 -0
- package/schemas/runtime-operations.schema.json +535 -0
- package/schemas/runtime-qualification-report.schema.json +540 -0
- package/schemas/runtime-session.schema.json +350 -0
- package/schemas/scene-spec.schema.json +624 -0
- package/schemas/skill-contract.schema.json +402 -0
- package/schemas/skill-eval.schema.json +509 -0
- package/scripts/build-knowledge-catalog.mjs +2376 -0
- package/scripts/compile-scene-plan.mjs +1945 -0
- package/scripts/export-claude-skills.mjs +634 -0
- package/scripts/generate-glb-handoff-report.mjs +2376 -0
- package/scripts/inspect-glb.mjs +1627 -0
- package/scripts/install-skills.mjs +5443 -0
- package/scripts/runtime-orchestrator.mjs +7713 -0
- package/scripts/validate-capability-policy.mjs +531 -0
- package/scripts/validate-evidence-packet.mjs +256 -0
- package/skills/README.md +315 -0
- package/skills/_template/SKILL.md +296 -0
- package/skills/acceptance-criteria-builder/EVAL.md +25 -0
- package/skills/acceptance-criteria-builder/SKILL.md +257 -0
- package/skills/acceptance-criteria-builder/contract.json +205 -0
- package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
- package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
- package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
- package/skills/asset-discovery/EVAL.md +81 -0
- package/skills/asset-discovery/SKILL.md +252 -0
- package/skills/asset-discovery/contract.json +291 -0
- package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
- package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
- package/skills/asset-discovery/references/license-confidence-table.md +41 -0
- package/skills/asset-fallback-strategy/EVAL.md +34 -0
- package/skills/asset-fallback-strategy/SKILL.md +248 -0
- package/skills/asset-fallback-strategy/contract.json +190 -0
- package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
- package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
- package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
- package/skills/asset-library-plan/EVAL.md +28 -0
- package/skills/asset-library-plan/SKILL.md +263 -0
- package/skills/asset-library-plan/contract.json +177 -0
- package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
- package/skills/asset-library-plan/references/metadata-schema.md +62 -0
- package/skills/asset-library-plan/references/naming-rules.md +51 -0
- package/skills/asset-license-checker/EVAL.md +33 -0
- package/skills/asset-license-checker/SKILL.md +245 -0
- package/skills/asset-license-checker/contract.json +172 -0
- package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
- package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
- package/skills/asset-license-checker/references/license-source-rules.md +38 -0
- package/skills/asset-style-check/EVAL.md +26 -0
- package/skills/asset-style-check/SKILL.md +238 -0
- package/skills/asset-style-check/contract.json +251 -0
- package/skills/asset-style-check/references/drift-classification.md +40 -0
- package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
- package/skills/asset-style-check/references/style-axes.md +46 -0
- package/skills/blender-brainstorming/EVAL.md +79 -0
- package/skills/blender-brainstorming/SKILL.md +228 -0
- package/skills/blender-brainstorming/contract.json +115 -0
- package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
- package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
- package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
- package/skills/blender-recipe-decomposer/EVAL.md +35 -0
- package/skills/blender-recipe-decomposer/SKILL.md +258 -0
- package/skills/blender-recipe-decomposer/contract.json +152 -0
- package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
- package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
- package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
- package/skills/blender-troubleshooting/EVAL.md +78 -0
- package/skills/blender-troubleshooting/SKILL.md +263 -0
- package/skills/blender-troubleshooting/contract.json +352 -0
- package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
- package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
- package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
- package/skills/blendops-help/EVAL.md +67 -0
- package/skills/blendops-help/SKILL.md +312 -0
- package/skills/blendops-help/contract.json +229 -0
- package/skills/blendops-help/references/lifecycle-phases.md +91 -0
- package/skills/blendops-help/references/quick-start-prompts.md +65 -0
- package/skills/blendops-help/references/routing-decision-tree.md +57 -0
- package/skills/bridge-conflicts/EVAL.md +83 -0
- package/skills/bridge-conflicts/SKILL.md +246 -0
- package/skills/bridge-conflicts/contract.json +145 -0
- package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
- package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
- package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
- package/skills/camera-composition/EVAL.md +32 -0
- package/skills/camera-composition/SKILL.md +196 -0
- package/skills/camera-composition/contract.json +180 -0
- package/skills/camera-composition/references/camera-presets.md +30 -0
- package/skills/camera-composition/references/camera-rubric.md +24 -0
- package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
- package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
- package/skills/character-portrait/EVAL.md +42 -0
- package/skills/character-portrait/SKILL.md +245 -0
- package/skills/character-portrait/contract.json +205 -0
- package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
- package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
- package/skills/character-portrait/references/style-consistency-rules.md +41 -0
- package/skills/cli-appendix-job-outline/EVAL.md +26 -0
- package/skills/cli-appendix-job-outline/SKILL.md +252 -0
- package/skills/cli-appendix-job-outline/contract.json +147 -0
- package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
- package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
- package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
- package/skills/color-management-decision/EVAL.md +28 -0
- package/skills/color-management-decision/SKILL.md +254 -0
- package/skills/color-management-decision/contract.json +162 -0
- package/skills/color-management-decision/references/look-comparison.md +44 -0
- package/skills/color-management-decision/references/per-channel-rules.md +49 -0
- package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
- package/skills/composition-quality-checker/EVAL.md +38 -0
- package/skills/composition-quality-checker/SKILL.md +260 -0
- package/skills/composition-quality-checker/contract.json +221 -0
- package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
- package/skills/composition-quality-checker/references/composition-rules.md +58 -0
- package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
- package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
- package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
- package/skills/cycles-vs-eevee-decision/contract.json +142 -0
- package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
- package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
- package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
- package/skills/done-criteria/EVAL.md +33 -0
- package/skills/done-criteria/SKILL.md +225 -0
- package/skills/done-criteria/contract.json +199 -0
- package/skills/done-criteria/references/done-vs-perfect.md +56 -0
- package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
- package/skills/done-criteria/references/stop-condition-templates.md +39 -0
- package/skills/environment-shot/EVAL.md +44 -0
- package/skills/environment-shot/SKILL.md +237 -0
- package/skills/environment-shot/contract.json +162 -0
- package/skills/environment-shot/references/depth-layering-rules.md +49 -0
- package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
- package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
- package/skills/glb-animation-handoff/EVAL.md +39 -0
- package/skills/glb-animation-handoff/SKILL.md +271 -0
- package/skills/glb-animation-handoff/contract.json +247 -0
- package/skills/glb-animation-handoff/references/animation-types.md +36 -0
- package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
- package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
- package/skills/glb-web-handoff/EVAL.md +33 -0
- package/skills/glb-web-handoff/SKILL.md +212 -0
- package/skills/glb-web-handoff/contract.json +171 -0
- package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
- package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
- package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
- package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
- package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
- package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
- package/skills/intent-to-3d-brief-writer/contract.json +195 -0
- package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
- package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
- package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
- package/skills/interior-scene/EVAL.md +44 -0
- package/skills/interior-scene/SKILL.md +261 -0
- package/skills/interior-scene/contract.json +277 -0
- package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
- package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
- package/skills/interior-scene/references/interior-camera-rules.md +47 -0
- package/skills/lighting-material-plan/EVAL.md +32 -0
- package/skills/lighting-material-plan/SKILL.md +194 -0
- package/skills/lighting-material-plan/contract.json +213 -0
- package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
- package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
- package/skills/lighting-material-plan/references/material-portability.md +25 -0
- package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
- package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
- package/skills/lighting-quality-checker/EVAL.md +41 -0
- package/skills/lighting-quality-checker/SKILL.md +247 -0
- package/skills/lighting-quality-checker/contract.json +187 -0
- package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
- package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
- package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
- package/skills/material-quality-checker/EVAL.md +40 -0
- package/skills/material-quality-checker/SKILL.md +261 -0
- package/skills/material-quality-checker/contract.json +244 -0
- package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
- package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
- package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
- package/skills/mobile-glb-budget/EVAL.md +40 -0
- package/skills/mobile-glb-budget/SKILL.md +264 -0
- package/skills/mobile-glb-budget/contract.json +309 -0
- package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
- package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
- package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
- package/skills/output-format-decision/EVAL.md +27 -0
- package/skills/output-format-decision/SKILL.md +222 -0
- package/skills/output-format-decision/contract.json +179 -0
- package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
- package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
- package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
- package/skills/pack-prerequisite-checker/EVAL.md +26 -0
- package/skills/pack-prerequisite-checker/SKILL.md +272 -0
- package/skills/pack-prerequisite-checker/contract.json +214 -0
- package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
- package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
- package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
- package/skills/path-one-host-outline/EVAL.md +26 -0
- package/skills/path-one-host-outline/SKILL.md +251 -0
- package/skills/path-one-host-outline/contract.json +167 -0
- package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
- package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
- package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
- package/skills/plain-language-response/EVAL.md +33 -0
- package/skills/plain-language-response/SKILL.md +194 -0
- package/skills/plain-language-response/contract.json +242 -0
- package/skills/plain-language-response/references/caveat-language.md +25 -0
- package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
- package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
- package/skills/plain-language-response/references/status-summary-templates.md +50 -0
- package/skills/polycount-budget-checker/EVAL.md +40 -0
- package/skills/polycount-budget-checker/SKILL.md +251 -0
- package/skills/polycount-budget-checker/contract.json +196 -0
- package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
- package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
- package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
- package/skills/pre-handoff-verification/EVAL.md +84 -0
- package/skills/pre-handoff-verification/SKILL.md +252 -0
- package/skills/pre-handoff-verification/contract.json +295 -0
- package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
- package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
- package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
- package/skills/preview-report/EVAL.md +39 -0
- package/skills/preview-report/SKILL.md +254 -0
- package/skills/preview-report/contract.json +141 -0
- package/skills/preview-report/references/handoff-recipients.md +41 -0
- package/skills/preview-report/references/report-schema.md +60 -0
- package/skills/preview-report/references/truth-label-rules.md +36 -0
- package/skills/product-grid-scene-planner/EVAL.md +42 -0
- package/skills/product-grid-scene-planner/SKILL.md +246 -0
- package/skills/product-grid-scene-planner/contract.json +257 -0
- package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
- package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
- package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
- package/skills/product-hero-scene-planner/EVAL.md +33 -0
- package/skills/product-hero-scene-planner/SKILL.md +227 -0
- package/skills/product-hero-scene-planner/contract.json +228 -0
- package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
- package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
- package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
- package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
- package/skills/r3f-component-plan/EVAL.md +43 -0
- package/skills/r3f-component-plan/SKILL.md +290 -0
- package/skills/r3f-component-plan/contract.json +171 -0
- package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
- package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
- package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
- package/skills/recipe-fit-assessor/EVAL.md +28 -0
- package/skills/recipe-fit-assessor/SKILL.md +266 -0
- package/skills/recipe-fit-assessor/contract.json +220 -0
- package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
- package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
- package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
- package/skills/render-export-evidence/EVAL.md +86 -0
- package/skills/render-export-evidence/SKILL.md +339 -0
- package/skills/render-export-evidence/contract.json +206 -0
- package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
- package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
- package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
- package/skills/resolution-aspect-decision/EVAL.md +26 -0
- package/skills/resolution-aspect-decision/SKILL.md +246 -0
- package/skills/resolution-aspect-decision/contract.json +160 -0
- package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
- package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
- package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
- package/skills/runtime-attempt-report/EVAL.md +26 -0
- package/skills/runtime-attempt-report/SKILL.md +268 -0
- package/skills/runtime-attempt-report/contract.json +176 -0
- package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
- package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
- package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
- package/skills/runtime-path-picker/EVAL.md +26 -0
- package/skills/runtime-path-picker/SKILL.md +268 -0
- package/skills/runtime-path-picker/contract.json +191 -0
- package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
- package/skills/runtime-path-picker/references/decision-tree.md +29 -0
- package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
- package/skills/runtime-readiness/EVAL.md +33 -0
- package/skills/runtime-readiness/SKILL.md +218 -0
- package/skills/runtime-readiness/contract.json +190 -0
- package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
- package/skills/runtime-readiness/references/evidence-examples.md +23 -0
- package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
- package/skills/runtime-setup/EVAL.md +33 -0
- package/skills/runtime-setup/SKILL.md +209 -0
- package/skills/runtime-setup/contract.json +171 -0
- package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
- package/skills/runtime-setup/references/setup-summary-template.md +33 -0
- package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
- package/skills/scene-readiness/EVAL.md +33 -0
- package/skills/scene-readiness/SKILL.md +195 -0
- package/skills/scene-readiness/contract.json +198 -0
- package/skills/scene-readiness/references/blocker-catalog.md +24 -0
- package/skills/scene-readiness/references/not-run-handling.md +22 -0
- package/skills/scene-readiness/references/quality-rubric.md +23 -0
- package/skills/scene-readiness/references/verdict-language.md +22 -0
- package/skills/scope-guard/EVAL.md +33 -0
- package/skills/scope-guard/SKILL.md +222 -0
- package/skills/scope-guard/contract.json +171 -0
- package/skills/scope-guard/references/options-language-template.md +51 -0
- package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
- package/skills/scope-guard/references/scope-addition-classification.md +55 -0
- package/skills/stage-gates/EVAL.md +40 -0
- package/skills/stage-gates/SKILL.md +257 -0
- package/skills/stage-gates/contract.json +490 -0
- package/skills/stage-gates/references/failed-gate-handling.md +42 -0
- package/skills/stage-gates/references/gate-template.md +46 -0
- package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
- package/skills/workflow-stage-router/EVAL.md +25 -0
- package/skills/workflow-stage-router/SKILL.md +259 -0
- package/skills/workflow-stage-router/contract.json +150 -0
- package/skills/workflow-stage-router/references/milestone-model.md +20 -0
- package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
- package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
- package/skills.sh.json +102 -0
|
@@ -0,0 +1,1945 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* BlendOps — SceneSpec Validator, Skill Harmonizer & Deterministic Plan Compiler
|
|
4
|
+
*
|
|
5
|
+
* Implements:
|
|
6
|
+
* - validateSceneSpec(specOrPath, options): Real JSON Schema Draft 2020-12 (Ajv2020) + semantic + canonical catalog validation
|
|
7
|
+
* - compileExecutionPlan(specOrPath, options): Deterministic recipe selection (recipe-fit-assessor),
|
|
8
|
+
* sub-goal decomposition (blender-recipe-decomposer), 8-layer precedence resolution, cross-skill
|
|
9
|
+
* conflict detection (blocking / warning / informational), and Ajv2020 ExecutionPlan validation
|
|
10
|
+
* - inspectExecutionPlan(planOrPath, options): Schema + cross-layer semantic invariant verification of a compiled plan
|
|
11
|
+
* - runPlanCliSubcommand(argv, options): CLI integration for scene-spec-validate, plan-compile, plan-inspect
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import fs from 'node:fs';
|
|
15
|
+
import os from 'node:os';
|
|
16
|
+
import path from 'node:path';
|
|
17
|
+
import { fileURLToPath } from 'node:url';
|
|
18
|
+
import Ajv2020 from 'ajv/dist/2020.js';
|
|
19
|
+
|
|
20
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
21
|
+
const __dirname = path.dirname(__filename);
|
|
22
|
+
const DEFAULT_REPO_ROOT = path.resolve(__dirname, '..');
|
|
23
|
+
|
|
24
|
+
export const PRECEDENCE_HIERARCHY = [
|
|
25
|
+
{
|
|
26
|
+
rank: 1,
|
|
27
|
+
layer_id: 'layer_1_hard_laws_and_safety',
|
|
28
|
+
name: 'Hard BlendOps Laws & Safety Invariants',
|
|
29
|
+
description:
|
|
30
|
+
'Non-negotiable BlendOps laws (evidence-before-done, no-arbitrary-python-interface, official-runtime-only, non-blender-user-language) and non-destructive geometry/shape-key safety rules.',
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
rank: 2,
|
|
34
|
+
layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
35
|
+
name: 'Target Delivery Format & Specification Constraints',
|
|
36
|
+
description:
|
|
37
|
+
'Hard format limits imposed by target delivery standards (e.g., Khronos glTF 2.0 single 0-1 UV space, <= 4 normalized bone weights, realized Geometry Nodes instances, baked PBR image textures).',
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
rank: 3,
|
|
41
|
+
layer_id: 'layer_3_runtime_and_blender_version_limits',
|
|
42
|
+
name: 'Runtime Execution Path & Blender Version Floor',
|
|
43
|
+
description:
|
|
44
|
+
'Capabilities and version floors of the selected execution path (Path 1 Official Blender Lab MCP requires Blender 5.1+, Path 2 Community mcp-for-blender supports Blender 3.0+, CLI Appendix headless).',
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
rank: 4,
|
|
48
|
+
layer_id: 'layer_4_explicit_performance_and_resource_budgets',
|
|
49
|
+
name: 'Explicit Performance, Triangle, Draw-Call & VRAM Budgets',
|
|
50
|
+
description:
|
|
51
|
+
'Target platform resource envelopes (mobile_web, desktop_web, hybrid_render_and_web, offline_cinema) enforced by polycount-budget-checker and mobile-glb-budget.',
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
rank: 5,
|
|
55
|
+
layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
56
|
+
name: 'Explicit User SceneSpec Parameters',
|
|
57
|
+
description:
|
|
58
|
+
'User-specified camera lens, aspect ratio, color management (AgX), lighting rig, and material style parameters declared in the SceneSpec.',
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
rank: 6,
|
|
62
|
+
layer_id: 'layer_6_domain_recipe_defaults',
|
|
63
|
+
name: 'Canonical Domain Recipe Defaults',
|
|
64
|
+
description:
|
|
65
|
+
'Default workflow sequences, required skills, and domain checks from the selected primary and supporting recipes in registry/recipe-catalog.json.',
|
|
66
|
+
},
|
|
67
|
+
{
|
|
68
|
+
rank: 7,
|
|
69
|
+
layer_id: 'layer_7_skill_level_heuristics',
|
|
70
|
+
name: 'Canonical Skill Heuristics',
|
|
71
|
+
description:
|
|
72
|
+
'Stage-level guidance and quality checklists defined in individual canonical skills/*/SKILL.md files.',
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
rank: 8,
|
|
76
|
+
layer_id: 'layer_8_aesthetic_fallbacks',
|
|
77
|
+
name: 'General Studio & Presentation Aesthetic Fallbacks',
|
|
78
|
+
description:
|
|
79
|
+
'Fallback framing, neutral studio backdrop, and default lighting ratios used when no higher-priority constraint specifies a value.',
|
|
80
|
+
},
|
|
81
|
+
];
|
|
82
|
+
|
|
83
|
+
function readJsonFile(filePath) {
|
|
84
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function formatAjvErrors(errors = []) {
|
|
88
|
+
return errors.map((err) => {
|
|
89
|
+
const loc = err.instancePath || '/';
|
|
90
|
+
return `${loc} ${err.message}`;
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const PROTECTED_REPO_PREFIXES = [
|
|
95
|
+
'registry',
|
|
96
|
+
'schemas',
|
|
97
|
+
'skills',
|
|
98
|
+
'scripts',
|
|
99
|
+
'laws',
|
|
100
|
+
'packs',
|
|
101
|
+
'bundles',
|
|
102
|
+
'bin',
|
|
103
|
+
'docs',
|
|
104
|
+
'evals',
|
|
105
|
+
'.git',
|
|
106
|
+
'.github',
|
|
107
|
+
'node_modules',
|
|
108
|
+
];
|
|
109
|
+
|
|
110
|
+
const PROTECTED_REPO_FILES = new Set([
|
|
111
|
+
'package.json',
|
|
112
|
+
'package-lock.json',
|
|
113
|
+
'AGENTS.md',
|
|
114
|
+
'README.md',
|
|
115
|
+
'TODO.md',
|
|
116
|
+
'CHANGELOG.md',
|
|
117
|
+
'CONTRIBUTING.md',
|
|
118
|
+
'CODE_OF_CONDUCT.md',
|
|
119
|
+
'SECURITY.md',
|
|
120
|
+
'SUPPORT.md',
|
|
121
|
+
'LICENSE',
|
|
122
|
+
]);
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Validates a CLI `--out` file path to prevent overwriting repository sources,
|
|
126
|
+
* global agent home directories, existing directories, or symbolic links.
|
|
127
|
+
*/
|
|
128
|
+
export function validateSafeCliOutFilePath(outPath, options = {}) {
|
|
129
|
+
const repoRoot = path.resolve(options.repoRoot || DEFAULT_REPO_ROOT);
|
|
130
|
+
if (!outPath || typeof outPath !== 'string' || outPath.includes('\0') || !outPath.trim()) {
|
|
131
|
+
return {
|
|
132
|
+
valid: false,
|
|
133
|
+
absPath: null,
|
|
134
|
+
error: 'Output path must be a non-empty string without null bytes.',
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const absOut = path.resolve(outPath);
|
|
139
|
+
const parsed = path.parse(absOut);
|
|
140
|
+
if (absOut === parsed.root) {
|
|
141
|
+
return {
|
|
142
|
+
valid: false,
|
|
143
|
+
absPath: absOut,
|
|
144
|
+
error: `Refusing to write to filesystem root: ${absOut}`,
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
const homeDir = os.homedir ? os.homedir() : process.env.HOME || '';
|
|
149
|
+
if (homeDir) {
|
|
150
|
+
const absHome = path.resolve(homeDir);
|
|
151
|
+
const forbiddenHomeDirs = [
|
|
152
|
+
'.claude',
|
|
153
|
+
'.cursor',
|
|
154
|
+
'.codex',
|
|
155
|
+
'.gemini',
|
|
156
|
+
'.windsurf',
|
|
157
|
+
'.continue',
|
|
158
|
+
'.cline',
|
|
159
|
+
'.roo',
|
|
160
|
+
'.github',
|
|
161
|
+
'.config',
|
|
162
|
+
];
|
|
163
|
+
for (const dirName of forbiddenHomeDirs) {
|
|
164
|
+
const candidate = path.join(absHome, dirName);
|
|
165
|
+
if (absOut === candidate || absOut.startsWith(candidate + path.sep)) {
|
|
166
|
+
return {
|
|
167
|
+
valid: false,
|
|
168
|
+
absPath: absOut,
|
|
169
|
+
error: `Refusing to write to global agent/home configuration path: ${absOut}`,
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
// Prevent overwriting repository source-of-truth files or directories
|
|
176
|
+
const relToRepo = path.relative(repoRoot, absOut);
|
|
177
|
+
if (!relToRepo.startsWith('..') && !path.isAbsolute(relToRepo)) {
|
|
178
|
+
const normalizedRel = relToRepo.split(path.sep).join('/');
|
|
179
|
+
if (normalizedRel === '' || PROTECTED_REPO_FILES.has(normalizedRel)) {
|
|
180
|
+
return {
|
|
181
|
+
valid: false,
|
|
182
|
+
absPath: absOut,
|
|
183
|
+
error: `Refusing to overwrite protected repository file or root: ${absOut}`,
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
const topSegment = normalizedRel.split('/')[0];
|
|
187
|
+
if (PROTECTED_REPO_PREFIXES.includes(topSegment)) {
|
|
188
|
+
return {
|
|
189
|
+
valid: false,
|
|
190
|
+
absPath: absOut,
|
|
191
|
+
error: `Refusing to write CLI output inside protected repository directory "${topSegment}/": ${absOut}`,
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
// Walk from root to absOut and reject any symbolic link along the path or at the target
|
|
197
|
+
const segments = absOut.slice(parsed.root.length).split(path.sep).filter(Boolean);
|
|
198
|
+
let cur = parsed.root;
|
|
199
|
+
for (let i = 0; i < segments.length; i++) {
|
|
200
|
+
cur = path.join(cur, segments[i]);
|
|
201
|
+
if (fs.existsSync(cur)) {
|
|
202
|
+
const st = fs.lstatSync(cur);
|
|
203
|
+
if (st.isSymbolicLink()) {
|
|
204
|
+
return {
|
|
205
|
+
valid: false,
|
|
206
|
+
absPath: absOut,
|
|
207
|
+
error: `Refusing to write through symbolic link at: ${cur}`,
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
if (i === segments.length - 1 && st.isDirectory()) {
|
|
211
|
+
return {
|
|
212
|
+
valid: false,
|
|
213
|
+
absPath: absOut,
|
|
214
|
+
error: `Output path already exists as a directory: ${absOut}`,
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
} else {
|
|
218
|
+
try {
|
|
219
|
+
const st = fs.lstatSync(cur);
|
|
220
|
+
if (st.isSymbolicLink()) {
|
|
221
|
+
return {
|
|
222
|
+
valid: false,
|
|
223
|
+
absPath: absOut,
|
|
224
|
+
error: `Refusing to write through dangling symbolic link at: ${cur}`,
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
} catch {
|
|
228
|
+
// does not exist
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
return { valid: true, absPath: absOut, error: null };
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
export function writeFileAtomicallySafe(outPath, content, options = {}) {
|
|
237
|
+
const check = validateSafeCliOutFilePath(outPath, options);
|
|
238
|
+
if (!check.valid) {
|
|
239
|
+
throw new Error(check.error);
|
|
240
|
+
}
|
|
241
|
+
const absOut = check.absPath;
|
|
242
|
+
const parentDir = path.dirname(absOut);
|
|
243
|
+
fs.mkdirSync(parentDir, { recursive: true });
|
|
244
|
+
const parentStat = fs.lstatSync(parentDir);
|
|
245
|
+
if (parentStat.isSymbolicLink() || !parentStat.isDirectory()) {
|
|
246
|
+
throw new Error(`Output parent directory is not a real directory: ${parentDir}`);
|
|
247
|
+
}
|
|
248
|
+
const tmpPath = path.join(
|
|
249
|
+
parentDir,
|
|
250
|
+
`.${path.basename(absOut)}.tmp-${process.pid}-${Date.now()}`,
|
|
251
|
+
);
|
|
252
|
+
fs.writeFileSync(tmpPath, content, 'utf8');
|
|
253
|
+
fs.renameSync(tmpPath, absOut);
|
|
254
|
+
return absOut;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
export function parseMajorMinorVersion(verStr) {
|
|
258
|
+
if (!verStr || typeof verStr !== 'string') return null;
|
|
259
|
+
const m = verStr.trim().match(/^(\d+)\.(\d+)/);
|
|
260
|
+
if (!m) return null;
|
|
261
|
+
const major = Number(m[1]);
|
|
262
|
+
const minor = Number(m[2]);
|
|
263
|
+
return { major, minor, num: major * 100 + minor };
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
export function extractBlenderVersionBounds(versionTarget) {
|
|
267
|
+
if (!versionTarget || typeof versionTarget !== 'object') {
|
|
268
|
+
return { minVer: null, recVer: null, rangeMinVer: null, rangeMaxVer: null, effectiveMaxVer: null };
|
|
269
|
+
}
|
|
270
|
+
const minParsed = parseMajorMinorVersion(versionTarget.min);
|
|
271
|
+
const recParsed = parseMajorMinorVersion(versionTarget.recommended);
|
|
272
|
+
let rangeMinParsed = null;
|
|
273
|
+
let rangeMaxParsed = null;
|
|
274
|
+
if (typeof versionTarget.tested_range === 'string') {
|
|
275
|
+
const parts = versionTarget.tested_range.split('-').map((s) => s.trim());
|
|
276
|
+
if (parts.length === 2) {
|
|
277
|
+
rangeMinParsed = parseMajorMinorVersion(parts[0]);
|
|
278
|
+
rangeMaxParsed = parseMajorMinorVersion(parts[1]);
|
|
279
|
+
} else if (parts.length === 1) {
|
|
280
|
+
rangeMinParsed = parseMajorMinorVersion(parts[0]);
|
|
281
|
+
rangeMaxParsed = rangeMinParsed;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
const minVer = minParsed ? minParsed.num : null;
|
|
285
|
+
const recVer = recParsed ? recParsed.num : null;
|
|
286
|
+
const rangeMinVer = rangeMinParsed ? rangeMinParsed.num : null;
|
|
287
|
+
const rangeMaxVer = rangeMaxParsed ? rangeMaxParsed.num : null;
|
|
288
|
+
const candidates = [recVer, rangeMaxVer].filter((x) => x !== null);
|
|
289
|
+
const effectiveMaxVer =
|
|
290
|
+
candidates.length > 0 ? Math.max(...candidates) : minVer !== null ? minVer : null;
|
|
291
|
+
return {
|
|
292
|
+
minVer,
|
|
293
|
+
recVer,
|
|
294
|
+
rangeMinVer,
|
|
295
|
+
rangeMaxVer,
|
|
296
|
+
effectiveMaxVer,
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Resolves catalog files from either a project-local `.blendops/catalog` directory
|
|
302
|
+
* (if `projectDir` is provided and installed) or the repository root.
|
|
303
|
+
*/
|
|
304
|
+
export function resolveCatalogPaths(repoRoot = DEFAULT_REPO_ROOT, projectDir = null) {
|
|
305
|
+
if (projectDir) {
|
|
306
|
+
const absProject = path.resolve(projectDir);
|
|
307
|
+
const localCatalogDir = path.join(absProject, '.blendops', 'catalog');
|
|
308
|
+
const localKnowledgePath = path.join(localCatalogDir, 'knowledge-catalog.json');
|
|
309
|
+
const localRecipePath = path.join(localCatalogDir, 'recipe-catalog.json');
|
|
310
|
+
const localSourcesPath = path.join(localCatalogDir, 'knowledge-sources.json');
|
|
311
|
+
if (
|
|
312
|
+
fs.existsSync(localKnowledgePath) &&
|
|
313
|
+
fs.existsSync(localRecipePath) &&
|
|
314
|
+
fs.existsSync(localSourcesPath)
|
|
315
|
+
) {
|
|
316
|
+
return {
|
|
317
|
+
sourceMode: 'project-local',
|
|
318
|
+
catalogDir: localCatalogDir,
|
|
319
|
+
knowledgeCatalogPath: localKnowledgePath,
|
|
320
|
+
recipeCatalogPath: localRecipePath,
|
|
321
|
+
knowledgeSourcesPath: localSourcesPath,
|
|
322
|
+
catalogIndexPath: path.join(localCatalogDir, 'catalog-index.json'),
|
|
323
|
+
skillsPath: fs.existsSync(path.join(localCatalogDir, 'skills-summary.json'))
|
|
324
|
+
? path.join(localCatalogDir, 'skills-summary.json')
|
|
325
|
+
: path.join(repoRoot, 'registry', 'skills.json'),
|
|
326
|
+
schemasDir: fs.existsSync(path.join(localCatalogDir, 'schemas', 'scene-spec.schema.json'))
|
|
327
|
+
? path.join(localCatalogDir, 'schemas')
|
|
328
|
+
: path.join(repoRoot, 'schemas'),
|
|
329
|
+
};
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
return {
|
|
333
|
+
sourceMode: 'repository',
|
|
334
|
+
catalogDir: path.join(repoRoot, 'registry'),
|
|
335
|
+
knowledgeCatalogPath: path.join(repoRoot, 'registry', 'knowledge-catalog.json'),
|
|
336
|
+
recipeCatalogPath: path.join(repoRoot, 'registry', 'recipe-catalog.json'),
|
|
337
|
+
knowledgeSourcesPath: path.join(repoRoot, 'registry', 'knowledge-sources.json'),
|
|
338
|
+
catalogIndexPath: path.join(repoRoot, 'registry', 'catalog-index.json'),
|
|
339
|
+
skillsPath: path.join(repoRoot, 'registry', 'skills.json'),
|
|
340
|
+
schemasDir: path.join(repoRoot, 'schemas'),
|
|
341
|
+
};
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
function loadInputJson(objOrPath) {
|
|
345
|
+
if (typeof objOrPath === 'string') {
|
|
346
|
+
const absPath = path.resolve(objOrPath);
|
|
347
|
+
if (!fs.existsSync(absPath)) {
|
|
348
|
+
throw new Error(`File not found: ${absPath}`);
|
|
349
|
+
}
|
|
350
|
+
return { data: readJsonFile(absPath), filePath: absPath };
|
|
351
|
+
}
|
|
352
|
+
if (objOrPath && typeof objOrPath === 'object') {
|
|
353
|
+
return { data: objOrPath, filePath: null };
|
|
354
|
+
}
|
|
355
|
+
throw new Error('Expected a file path or JSON object.');
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
export const PRIMARY_GOAL_TO_RECIPE_ID = {
|
|
359
|
+
product_hero_presentation: 'recipe.product-hero-scene',
|
|
360
|
+
environment_or_diorama_scene: 'recipe.stylized-environment-scene',
|
|
361
|
+
hard_surface_prop_asset: 'recipe.hard-surface-prop',
|
|
362
|
+
procedural_geometry_nodes_asset: 'recipe.procedural-geometry-nodes-asset',
|
|
363
|
+
rigged_character_or_animation: 'recipe.rigged-and-animated-asset',
|
|
364
|
+
web_glb_optimization_and_handoff: 'recipe.web-ready-asset-optimization',
|
|
365
|
+
scene_quality_inspection_and_cleanup: 'recipe.scene-quality-inspection-and-correction',
|
|
366
|
+
hybrid_render_and_web_glb: 'recipe.product-hero-scene',
|
|
367
|
+
};
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Validates a SceneSpec against schemas/scene-spec.schema.json (Draft 2020-12)
|
|
371
|
+
* plus semantic and canonical catalog invariants.
|
|
372
|
+
*/
|
|
373
|
+
export function validateSceneSpec(specOrPath, options = {}) {
|
|
374
|
+
const repoRoot = options.repoRoot || DEFAULT_REPO_ROOT;
|
|
375
|
+
const projectDir = options.projectDir || null;
|
|
376
|
+
const catalogPaths = resolveCatalogPaths(repoRoot, projectDir);
|
|
377
|
+
const { schemasDir, recipeCatalogPath, sourceMode } = catalogPaths;
|
|
378
|
+
const schemaPath = path.join(schemasDir, 'scene-spec.schema.json');
|
|
379
|
+
const schema = readJsonFile(schemaPath);
|
|
380
|
+
|
|
381
|
+
let spec;
|
|
382
|
+
try {
|
|
383
|
+
spec = loadInputJson(specOrPath).data;
|
|
384
|
+
} catch (err) {
|
|
385
|
+
return {
|
|
386
|
+
valid: false,
|
|
387
|
+
errors: [err.message],
|
|
388
|
+
warnings: [],
|
|
389
|
+
spec: null,
|
|
390
|
+
spec_id: null,
|
|
391
|
+
runtime_status: 'Not Run',
|
|
392
|
+
artifact_status: 'Not Produced',
|
|
393
|
+
};
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
const ajv = new Ajv2020({ allErrors: true, strict: false });
|
|
397
|
+
const validate = ajv.compile(schema);
|
|
398
|
+
const errors = [];
|
|
399
|
+
const warnings = [];
|
|
400
|
+
|
|
401
|
+
if (!validate(spec)) {
|
|
402
|
+
for (const msg of formatAjvErrors(validate.errors)) {
|
|
403
|
+
errors.push(`scene-spec schema error: ${msg}`);
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
let recipesById = new Map();
|
|
408
|
+
try {
|
|
409
|
+
const recipeCatalog = readJsonFile(recipeCatalogPath);
|
|
410
|
+
recipesById = new Map((recipeCatalog.recipes || []).map((r) => [r.id, r]));
|
|
411
|
+
} catch (err) {
|
|
412
|
+
errors.push(`Failed to load canonical recipe catalog (${recipeCatalogPath}): ${err.message}`);
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
if (spec && typeof spec === 'object') {
|
|
416
|
+
// 1. Canonical recipe override and primary goal recipe resolution check (Defect 2A)
|
|
417
|
+
const explicitOverride = spec.intent?.explicit_recipe_override;
|
|
418
|
+
if (explicitOverride !== undefined && explicitOverride !== null) {
|
|
419
|
+
if (typeof explicitOverride !== 'string' || !/^recipe\.[a-z0-9-]+$/.test(explicitOverride)) {
|
|
420
|
+
errors.push(
|
|
421
|
+
`Invalid intent.explicit_recipe_override "${String(explicitOverride)}": must match ^recipe\\.[a-z0-9-]+$.`,
|
|
422
|
+
);
|
|
423
|
+
} else if (!recipesById.has(explicitOverride)) {
|
|
424
|
+
errors.push(
|
|
425
|
+
`Unresolved intent.explicit_recipe_override "${explicitOverride}": recipe does not exist in canonical recipe catalog (${sourceMode}).`,
|
|
426
|
+
);
|
|
427
|
+
}
|
|
428
|
+
} else if (spec.intent?.primary_goal) {
|
|
429
|
+
const mappedPrimary = PRIMARY_GOAL_TO_RECIPE_ID[spec.intent.primary_goal];
|
|
430
|
+
if (!mappedPrimary || !recipesById.has(mappedPrimary)) {
|
|
431
|
+
errors.push(
|
|
432
|
+
`Cannot resolve canonical primary recipe for intent.primary_goal "${spec.intent.primary_goal}" in ${sourceMode} recipe catalog.`,
|
|
433
|
+
);
|
|
434
|
+
}
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
// 2. Blender version target internal ordering sanity check
|
|
438
|
+
if (spec.blender_version_target && typeof spec.blender_version_target === 'object') {
|
|
439
|
+
const bounds = extractBlenderVersionBounds(spec.blender_version_target);
|
|
440
|
+
if (bounds.minVer !== null && bounds.recVer !== null && bounds.minVer > bounds.recVer) {
|
|
441
|
+
errors.push(
|
|
442
|
+
`blender_version_target.min (${spec.blender_version_target.min}) cannot exceed recommended (${spec.blender_version_target.recommended}).`,
|
|
443
|
+
);
|
|
444
|
+
}
|
|
445
|
+
if (
|
|
446
|
+
bounds.rangeMinVer !== null &&
|
|
447
|
+
bounds.rangeMaxVer !== null &&
|
|
448
|
+
bounds.rangeMaxVer < bounds.rangeMinVer
|
|
449
|
+
) {
|
|
450
|
+
errors.push(
|
|
451
|
+
`blender_version_target.tested_range (${spec.blender_version_target.tested_range}) has end version < start version.`,
|
|
452
|
+
);
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
if (Array.isArray(spec.objects_and_subjects)) {
|
|
457
|
+
const seenIds = new Set();
|
|
458
|
+
for (const obj of spec.objects_and_subjects) {
|
|
459
|
+
if (obj && obj.id) {
|
|
460
|
+
if (seenIds.has(obj.id)) {
|
|
461
|
+
errors.push(`Duplicate objects_and_subjects[].id: ${obj.id}`);
|
|
462
|
+
}
|
|
463
|
+
seenIds.add(obj.id);
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
if (
|
|
469
|
+
spec.animation_and_rigging &&
|
|
470
|
+
Array.isArray(spec.animation_and_rigging.frame_range) &&
|
|
471
|
+
spec.animation_and_rigging.frame_range.length === 2
|
|
472
|
+
) {
|
|
473
|
+
const [start, end] = spec.animation_and_rigging.frame_range;
|
|
474
|
+
if (end < start) {
|
|
475
|
+
errors.push(`animation_and_rigging.frame_range end (${end}) must be >= start (${start})`);
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
if (
|
|
480
|
+
spec.camera_and_framing &&
|
|
481
|
+
typeof spec.camera_and_framing.clip_start_m === 'number' &&
|
|
482
|
+
typeof spec.camera_and_framing.clip_end_m === 'number'
|
|
483
|
+
) {
|
|
484
|
+
if (spec.camera_and_framing.clip_end_m <= spec.camera_and_framing.clip_start_m) {
|
|
485
|
+
errors.push(
|
|
486
|
+
`camera_and_framing.clip_end_m (${spec.camera_and_framing.clip_end_m}) must be > clip_start_m (${spec.camera_and_framing.clip_start_m})`,
|
|
487
|
+
);
|
|
488
|
+
} else if (
|
|
489
|
+
spec.camera_and_framing.clip_end_m / spec.camera_and_framing.clip_start_m >
|
|
490
|
+
100000
|
|
491
|
+
) {
|
|
492
|
+
warnings.push(
|
|
493
|
+
`Camera far/near clip ratio (${Math.round(spec.camera_and_framing.clip_end_m / spec.camera_and_framing.clip_start_m)}:1) exceeds 100,000:1 and risks Z-fighting.`,
|
|
494
|
+
);
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
return {
|
|
500
|
+
valid: errors.length === 0,
|
|
501
|
+
errors,
|
|
502
|
+
warnings,
|
|
503
|
+
spec: errors.length === 0 ? spec : spec || null,
|
|
504
|
+
spec_id: spec?.id || null,
|
|
505
|
+
title: spec?.title || null,
|
|
506
|
+
language: spec?.language || null,
|
|
507
|
+
catalog_source_mode: sourceMode,
|
|
508
|
+
runtime_status: 'Not Run',
|
|
509
|
+
artifact_status: 'Not Produced',
|
|
510
|
+
};
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
/**
|
|
514
|
+
* Resolves the primary recipe and supporting recipes using `recipe-fit-assessor`
|
|
515
|
+
* and decomposes sub-goals via `blender-recipe-decomposer`.
|
|
516
|
+
*/
|
|
517
|
+
function resolveRecipesForSpec(spec, recipesById) {
|
|
518
|
+
const primaryRecipeId =
|
|
519
|
+
spec.intent.explicit_recipe_override ||
|
|
520
|
+
PRIMARY_GOAL_TO_RECIPE_ID[spec.intent.primary_goal] ||
|
|
521
|
+
'recipe.product-hero-scene';
|
|
522
|
+
|
|
523
|
+
if (!recipesById.has(primaryRecipeId)) {
|
|
524
|
+
throw new Error(
|
|
525
|
+
`Unresolved primary recipe "${primaryRecipeId}": recipe does not exist in canonical catalog.`,
|
|
526
|
+
);
|
|
527
|
+
}
|
|
528
|
+
|
|
529
|
+
const supportingSet = new Set();
|
|
530
|
+
|
|
531
|
+
const needsScanOrCleanup =
|
|
532
|
+
spec.objects_and_subjects.some((o) => o.has_non_manifold_or_scan_noise || !o.transforms_applied) ||
|
|
533
|
+
spec.intent.primary_goal === 'scene_quality_inspection_and_cleanup';
|
|
534
|
+
if (needsScanOrCleanup && primaryRecipeId !== 'recipe.scene-quality-inspection-and-correction') {
|
|
535
|
+
supportingSet.add('recipe.scene-quality-inspection-and-correction');
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
const needsHardSurface = spec.objects_and_subjects.some(
|
|
539
|
+
(o) =>
|
|
540
|
+
o.source_type === 'hard_surface_modeled' ||
|
|
541
|
+
o.modifiers.includes('Boolean') ||
|
|
542
|
+
o.modifiers.includes('Bevel'),
|
|
543
|
+
);
|
|
544
|
+
if (needsHardSurface && primaryRecipeId !== 'recipe.hard-surface-prop') {
|
|
545
|
+
supportingSet.add('recipe.hard-surface-prop');
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
const needsGeometryNodes =
|
|
549
|
+
spec.simulation_and_vfx.simulation_types.includes('geometry_nodes_scatter') ||
|
|
550
|
+
spec.objects_and_subjects.some((o) => o.source_type === 'procedural_geometry_nodes');
|
|
551
|
+
if (needsGeometryNodes && primaryRecipeId !== 'recipe.procedural-geometry-nodes-asset') {
|
|
552
|
+
supportingSet.add('recipe.procedural-geometry-nodes-asset');
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
if (
|
|
556
|
+
(spec.style_and_materials.bake_procedural_to_pbr ||
|
|
557
|
+
spec.style_and_materials.shader_workflow === 'principled_bsdf_pbr' ||
|
|
558
|
+
spec.style_and_materials.shader_workflow === 'procedural_nodes_baked_to_textures') &&
|
|
559
|
+
primaryRecipeId !== 'recipe.uv-and-pbr-material-preparation'
|
|
560
|
+
) {
|
|
561
|
+
supportingSet.add('recipe.uv-and-pbr-material-preparation');
|
|
562
|
+
}
|
|
563
|
+
|
|
564
|
+
const rendersVisualOutput = spec.deliverables.formats.some((f) =>
|
|
565
|
+
['png_still', 'exr_multilayer', 'mp4_turntable'].includes(f),
|
|
566
|
+
);
|
|
567
|
+
if (rendersVisualOutput && primaryRecipeId !== 'recipe.presentation-lighting-and-camera') {
|
|
568
|
+
supportingSet.add('recipe.presentation-lighting-and-camera');
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
const deliversGlb = spec.deliverables.formats.some((f) =>
|
|
572
|
+
['glb_web_standard', 'gltf_extended'].includes(f),
|
|
573
|
+
);
|
|
574
|
+
if (deliversGlb) {
|
|
575
|
+
if (
|
|
576
|
+
(spec.optimization_and_budgets.target_tier === 'mobile_web' ||
|
|
577
|
+
spec.optimization_and_budgets.target_tier === 'hybrid_render_and_web' ||
|
|
578
|
+
spec.optimization_and_budgets.generate_lods) &&
|
|
579
|
+
primaryRecipeId !== 'recipe.web-ready-asset-optimization'
|
|
580
|
+
) {
|
|
581
|
+
supportingSet.add('recipe.web-ready-asset-optimization');
|
|
582
|
+
}
|
|
583
|
+
if (primaryRecipeId !== 'recipe.blender-to-glb-handoff') {
|
|
584
|
+
supportingSet.add('recipe.blender-to-glb-handoff');
|
|
585
|
+
}
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
const supportingRecipeIds = [];
|
|
589
|
+
for (const id of supportingSet) {
|
|
590
|
+
if (id === primaryRecipeId) continue;
|
|
591
|
+
if (!recipesById.has(id)) {
|
|
592
|
+
throw new Error(
|
|
593
|
+
`Unresolved supporting recipe "${id}": recipe does not exist in canonical catalog.`,
|
|
594
|
+
);
|
|
595
|
+
}
|
|
596
|
+
if (!supportingRecipeIds.includes(id)) {
|
|
597
|
+
supportingRecipeIds.push(id);
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
const orderedRecipeIds = [primaryRecipeId, ...supportingRecipeIds];
|
|
601
|
+
|
|
602
|
+
const decomposedSubGoals = orderedRecipeIds.map((recipeId, idx) => {
|
|
603
|
+
const rec = recipesById.get(recipeId);
|
|
604
|
+
if (!rec) {
|
|
605
|
+
throw new Error(`Recipe "${recipeId}" missing from canonical catalog during decomposition.`);
|
|
606
|
+
}
|
|
607
|
+
const recSkills = [
|
|
608
|
+
...new Set([...(rec.required_skill_ids || []), ...(rec.optional_skills || [])]),
|
|
609
|
+
];
|
|
610
|
+
const recKnowledge = [...new Set([...(rec.required_knowledge_ids || [])])];
|
|
611
|
+
return {
|
|
612
|
+
step_index: idx + 1,
|
|
613
|
+
recipe_id: recipeId,
|
|
614
|
+
sub_goal: `${rec.title}: ${rec.intent}`,
|
|
615
|
+
skills: recSkills,
|
|
616
|
+
knowledge_refs: recKnowledge,
|
|
617
|
+
};
|
|
618
|
+
});
|
|
619
|
+
|
|
620
|
+
const selectionRationale = `Selected primary recipe ${primaryRecipeId} for intent.primary_goal="${spec.intent.primary_goal}" via recipe-fit-assessor, decomposed into ${decomposedSubGoals.length} ordered sub-goal(s) via blender-recipe-decomposer (${supportingRecipeIds.length} supporting recipe(s): ${supportingRecipeIds.join(', ') || 'none'}).`;
|
|
621
|
+
|
|
622
|
+
return {
|
|
623
|
+
primary_recipe_id: primaryRecipeId,
|
|
624
|
+
supporting_recipe_ids: supportingRecipeIds,
|
|
625
|
+
selection_rationale: selectionRationale,
|
|
626
|
+
decomposed_sub_goals: decomposedSubGoals,
|
|
627
|
+
};
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
/**
|
|
631
|
+
* Detects cross-skill, format, budget, and runtime conflicts using the 8-layer precedence hierarchy.
|
|
632
|
+
*/
|
|
633
|
+
function detectConflicts(spec) {
|
|
634
|
+
const conflicts = [];
|
|
635
|
+
const deliversStandardGlb =
|
|
636
|
+
spec.deliverables.requires_standard_khronos_gltf_2_0 ||
|
|
637
|
+
spec.deliverables.formats.includes('glb_web_standard');
|
|
638
|
+
const glbOnlyDelivery =
|
|
639
|
+
spec.deliverables.formats.length === 1 &&
|
|
640
|
+
spec.deliverables.formats[0] === 'glb_web_standard';
|
|
641
|
+
|
|
642
|
+
// 1. UDIM multi-tile vs standard Khronos glTF 2.0 single 0-1 UV space
|
|
643
|
+
const usesUdim =
|
|
644
|
+
spec.style_and_materials.uv_packing === 'udim_tiles' ||
|
|
645
|
+
spec.style_and_materials.udim_tile_count > 1 ||
|
|
646
|
+
spec.objects_and_subjects.some((o) => o.uv_strategy === 'udim_multi_tile');
|
|
647
|
+
if (usesUdim && deliversStandardGlb) {
|
|
648
|
+
conflicts.push({
|
|
649
|
+
conflict_id: 'conflict.udim-vs-standard-glb',
|
|
650
|
+
severity: 'blocking',
|
|
651
|
+
rule_id: 'CONFLICT_UDIM_VS_STANDARD_GLB',
|
|
652
|
+
winning_layer_rank: 2,
|
|
653
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
654
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
655
|
+
summary:
|
|
656
|
+
'SceneSpec requests multi-tile UDIM UV packing (>1 tile in 1001+ range) together with standard Khronos glTF 2.0 GLB delivery. Core glTF 2.0 does not support multi-tile UDIM textures without baking/repacking into [0, 1] UV space or splitting materials per tile.',
|
|
657
|
+
affected_skills: ['glb-web-handoff', 'material-quality-checker', 'output-format-decision'],
|
|
658
|
+
knowledge_refs: [
|
|
659
|
+
'knowledge.udim-vs-single-atlas-uv-packing',
|
|
660
|
+
'knowledge.uv-seam-placement-and-texel-density',
|
|
661
|
+
],
|
|
662
|
+
remediation:
|
|
663
|
+
'Repack UV islands into a single [0, 1] UV atlas and bake multi-tile textures prior to GLB export, or assign separate material slots per tile with UV coordinates shifted into [0, 1].',
|
|
664
|
+
});
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
// 2. Cycles Volumetric Fog without bake/card fallback on GLB-only delivery
|
|
668
|
+
if (
|
|
669
|
+
spec.lighting_and_environment.volumetric_effects.enabled &&
|
|
670
|
+
!spec.lighting_and_environment.volumetric_effects.bake_or_card_fallback_for_realtime &&
|
|
671
|
+
glbOnlyDelivery
|
|
672
|
+
) {
|
|
673
|
+
conflicts.push({
|
|
674
|
+
conflict_id: 'conflict.volumetric-fog-glb-only',
|
|
675
|
+
severity: 'blocking',
|
|
676
|
+
rule_id: 'CONFLICT_VOLUMETRIC_FOG_GLB_ONLY',
|
|
677
|
+
winning_layer_rank: 2,
|
|
678
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
679
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
680
|
+
summary:
|
|
681
|
+
'SceneSpec enables Blender Cycles/EEVEE volumetric fog without a real-time card/shader fallback while only exporting a standard web GLB. Standard glTF 2.0 does not transport Blender Principled Volume shaders or Mantaflow smoke grids.',
|
|
682
|
+
affected_skills: ['lighting-material-plan', 'glb-web-handoff', 'output-format-decision'],
|
|
683
|
+
knowledge_refs: [
|
|
684
|
+
'knowledge.volumetrics-fog-and-principled-volume-tradeoffs',
|
|
685
|
+
'knowledge.rigid-body-cloth-and-simulation-cache-baking',
|
|
686
|
+
],
|
|
687
|
+
remediation:
|
|
688
|
+
'Enable bake_or_card_fallback_for_realtime (billboard alpha cards or Three.js host fog) for GLB delivery, or add png_still / exr_multilayer to deliverables for offline volumetric rendering.',
|
|
689
|
+
});
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
// 3. Unbaked Blender procedural shader nodes when delivering standard GLB
|
|
693
|
+
if (
|
|
694
|
+
(spec.style_and_materials.shader_workflow === 'procedural_nodes_unbaked' ||
|
|
695
|
+
(spec.style_and_materials.shader_workflow === 'toon_npr_shader' &&
|
|
696
|
+
!spec.style_and_materials.bake_procedural_to_pbr)) &&
|
|
697
|
+
deliversStandardGlb
|
|
698
|
+
) {
|
|
699
|
+
conflicts.push({
|
|
700
|
+
conflict_id: 'conflict.unbaked-procedural-shader-glb',
|
|
701
|
+
severity: 'blocking',
|
|
702
|
+
rule_id: 'CONFLICT_UNBAKED_PROCEDURAL_SHADER_GLB',
|
|
703
|
+
winning_layer_rank: 2,
|
|
704
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
705
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
706
|
+
summary:
|
|
707
|
+
'SceneSpec uses unbaked Blender procedural shader nodes (Noise/Voronoi/ColorRamp/Shader-to-RGB) while targeting standard glTF 2.0 GLB export. Blender procedural nodes are silently dropped by the glTF exporter unless baked to PBR image textures.',
|
|
708
|
+
affected_skills: ['lighting-material-plan', 'material-quality-checker', 'glb-web-handoff'],
|
|
709
|
+
knowledge_refs: [
|
|
710
|
+
'knowledge.shader-node-gltf-export-portability',
|
|
711
|
+
'knowledge.principled-bsdf-v2-energy-conserving-pbr',
|
|
712
|
+
],
|
|
713
|
+
remediation:
|
|
714
|
+
'Set shader_workflow to "procedural_nodes_baked_to_textures" and bake_procedural_to_pbr: true to bake Base Color, Roughness, Metallic, and MikkTSpace Normal maps before GLB export.',
|
|
715
|
+
});
|
|
716
|
+
}
|
|
717
|
+
|
|
718
|
+
// 4. Unrealized Geometry Nodes instances when delivering standard GLB
|
|
719
|
+
const hasGnObjects =
|
|
720
|
+
spec.simulation_and_vfx.simulation_types.includes('geometry_nodes_scatter') ||
|
|
721
|
+
spec.objects_and_subjects.some((o) => o.source_type === 'procedural_geometry_nodes');
|
|
722
|
+
if (hasGnObjects && !spec.simulation_and_vfx.geometry_nodes_realize_instances && deliversStandardGlb) {
|
|
723
|
+
conflicts.push({
|
|
724
|
+
conflict_id: 'conflict.unrealized-geometry-nodes-glb',
|
|
725
|
+
severity: 'blocking',
|
|
726
|
+
rule_id: 'CONFLICT_UNREALIZED_GEOMETRY_NODES_GLB',
|
|
727
|
+
winning_layer_rank: 2,
|
|
728
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
729
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
730
|
+
summary:
|
|
731
|
+
'SceneSpec includes Geometry Nodes procedural scatter/generator objects with geometry_nodes_realize_instances: false while targeting standard GLB export. Unrealized procedural instances and unmapped named attributes export as empty nodes or missing UVs.',
|
|
732
|
+
affected_skills: ['scene-readiness', 'glb-web-handoff', 'pre-handoff-verification'],
|
|
733
|
+
knowledge_refs: [
|
|
734
|
+
'knowledge.procedural-instancing-and-realize-instances-budget',
|
|
735
|
+
'knowledge.geometry-nodes-fields-and-anonymous-attributes',
|
|
736
|
+
],
|
|
737
|
+
remediation:
|
|
738
|
+
'Set simulation_and_vfx.geometry_nodes_realize_instances: true and store UV coordinates into an explicit Face Corner 2D Vector attribute named UVMap before GLB export.',
|
|
739
|
+
});
|
|
740
|
+
}
|
|
741
|
+
|
|
742
|
+
// 5. Unapplied transforms or negative/non-unit scale on export or rigged objects
|
|
743
|
+
const badScaleObjects = spec.objects_and_subjects.filter(
|
|
744
|
+
(o) =>
|
|
745
|
+
!o.transforms_applied ||
|
|
746
|
+
o.scale_factors.some((s) => s <= 0 || Math.abs(s - 1.0) > 1e-4),
|
|
747
|
+
);
|
|
748
|
+
if (badScaleObjects.length > 0 && (deliversStandardGlb || spec.animation_and_rigging.has_armature)) {
|
|
749
|
+
const hasNegativeScale = badScaleObjects.some((o) => o.scale_factors.some((s) => s < 0));
|
|
750
|
+
conflicts.push({
|
|
751
|
+
conflict_id: 'conflict.unapplied-or-negative-scale-export',
|
|
752
|
+
severity: 'blocking',
|
|
753
|
+
rule_id: 'CONFLICT_UNAPPLIED_OR_NEGATIVE_SCALE_EXPORT',
|
|
754
|
+
winning_layer_rank: 1,
|
|
755
|
+
winning_layer_id: 'layer_1_hard_laws_and_safety',
|
|
756
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
757
|
+
summary: `Object(s) [${badScaleObjects.map((o) => o.id).join(', ')}] have unapplied transforms or non-unit/negative scale (${hasNegativeScale ? 'negative scale inverts face winding and flips normals in glTF/Three.js' : 'non-unit scale distorts bevels, UVs, and skeletal skinning'}).`,
|
|
758
|
+
affected_skills: ['scene-readiness', 'pre-handoff-verification', 'glb-web-handoff'],
|
|
759
|
+
knowledge_refs: [
|
|
760
|
+
'knowledge.mesh-manifold-normals-and-scale-hygiene',
|
|
761
|
+
'knowledge.gltf-2-coordinate-system-and-transform-conventions',
|
|
762
|
+
],
|
|
763
|
+
remediation:
|
|
764
|
+
'Apply Rotation & Scale (Ctrl+A -> Rotation & Scale) so all exported/rigged objects have scale [1.0, 1.0, 1.0], and recalculate outward normals if negative scale was used.',
|
|
765
|
+
});
|
|
766
|
+
}
|
|
767
|
+
|
|
768
|
+
// 6. Bone influences per vertex > 4 for standard glTF 2.0 skinning
|
|
769
|
+
if (
|
|
770
|
+
spec.animation_and_rigging.has_armature &&
|
|
771
|
+
spec.animation_and_rigging.max_bone_influences_per_vertex > 4 &&
|
|
772
|
+
deliversStandardGlb
|
|
773
|
+
) {
|
|
774
|
+
conflicts.push({
|
|
775
|
+
conflict_id: 'conflict.bone-influences-exceed-gltf-limit',
|
|
776
|
+
severity: 'blocking',
|
|
777
|
+
rule_id: 'CONFLICT_BONE_INFLUENCES_EXCEED_GLTF_LIMIT',
|
|
778
|
+
winning_layer_rank: 2,
|
|
779
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
780
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
781
|
+
summary: `SceneSpec specifies max_bone_influences_per_vertex = ${spec.animation_and_rigging.max_bone_influences_per_vertex}, exceeding the core Khronos glTF 2.0 JOINTS_0 / WEIGHTS_0 limit of 4 normalized bone influences per vertex.`,
|
|
782
|
+
affected_skills: ['glb-animation-handoff', 'pre-handoff-verification'],
|
|
783
|
+
knowledge_refs: ['knowledge.armature-joint-hierarchy-and-linear-blend-skinning'],
|
|
784
|
+
remediation:
|
|
785
|
+
'Run Limit Total (<= 4 influences per vertex) and Normalize All in Weight Paint mode before exporting to glTF 2.0.',
|
|
786
|
+
});
|
|
787
|
+
}
|
|
788
|
+
|
|
789
|
+
// 7. Applying modifiers directly on a mesh with active Shape Keys
|
|
790
|
+
if (
|
|
791
|
+
spec.animation_and_rigging.has_shape_keys &&
|
|
792
|
+
spec.animation_and_rigging.apply_modifiers_with_shape_keys
|
|
793
|
+
) {
|
|
794
|
+
conflicts.push({
|
|
795
|
+
conflict_id: 'conflict.apply-modifiers-with-shape-keys',
|
|
796
|
+
severity: 'blocking',
|
|
797
|
+
rule_id: 'CONFLICT_APPLY_MODIFIERS_WITH_SHAPE_KEYS',
|
|
798
|
+
winning_layer_rank: 1,
|
|
799
|
+
winning_layer_id: 'layer_1_hard_laws_and_safety',
|
|
800
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
801
|
+
summary:
|
|
802
|
+
'SceneSpec sets apply_modifiers_with_shape_keys: true on a mesh with active Shape Keys. Blender cannot directly apply topology-changing modifiers on meshes with Shape Keys without destroying morph target vertex indices.',
|
|
803
|
+
affected_skills: ['glb-animation-handoff', 'scene-readiness'],
|
|
804
|
+
knowledge_refs: [
|
|
805
|
+
'knowledge.nla-action-baking-and-morph-target-export',
|
|
806
|
+
'knowledge.non-destructive-hard-surface-modifier-stack',
|
|
807
|
+
],
|
|
808
|
+
remediation:
|
|
809
|
+
'Set apply_modifiers_with_shape_keys: false, finalize base topology before authoring Shape Keys, or propagate modifiers across duplicated per-shape-key meshes and rejoin as shapes.',
|
|
810
|
+
});
|
|
811
|
+
}
|
|
812
|
+
|
|
813
|
+
// 8. Unbaked NLA / IK constraints when exporting animated GLB
|
|
814
|
+
if (
|
|
815
|
+
spec.animation_and_rigging.enabled &&
|
|
816
|
+
spec.animation_and_rigging.has_armature &&
|
|
817
|
+
!spec.animation_and_rigging.bake_nla_to_linear_keyframes &&
|
|
818
|
+
deliversStandardGlb
|
|
819
|
+
) {
|
|
820
|
+
conflicts.push({
|
|
821
|
+
conflict_id: 'conflict.unbaked-nla-constraints-glb',
|
|
822
|
+
severity: 'blocking',
|
|
823
|
+
rule_id: 'CONFLICT_UNBAKED_NLA_CONSTRAINTS_GLB',
|
|
824
|
+
winning_layer_rank: 2,
|
|
825
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
826
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
827
|
+
summary:
|
|
828
|
+
'SceneSpec enables armature animation for GLB delivery with bake_nla_to_linear_keyframes: false. Blender IK solvers, Copy Transforms, and Python driver expressions are not exported to glTF 2.0 unless baked to visual deformation keyframes.',
|
|
829
|
+
affected_skills: ['glb-animation-handoff', 'glb-web-handoff'],
|
|
830
|
+
knowledge_refs: ['knowledge.nla-action-baking-and-morph-target-export'],
|
|
831
|
+
remediation:
|
|
832
|
+
'Set bake_nla_to_linear_keyframes: true (Bake Action with Visual Keying, Clear Constraints, and Export Deform Bones Only).',
|
|
833
|
+
});
|
|
834
|
+
}
|
|
835
|
+
|
|
836
|
+
// 9. Polycount sum vs optimization_and_budgets.max_triangles
|
|
837
|
+
const totalObjectTriangles = spec.objects_and_subjects.reduce(
|
|
838
|
+
(sum, obj) => sum + (obj.poly_budget_triangles || 0),
|
|
839
|
+
0,
|
|
840
|
+
);
|
|
841
|
+
if (totalObjectTriangles > spec.optimization_and_budgets.max_triangles) {
|
|
842
|
+
const ratio = totalObjectTriangles / spec.optimization_and_budgets.max_triangles;
|
|
843
|
+
conflicts.push({
|
|
844
|
+
conflict_id: 'conflict.poly-sum-exceeds-budget',
|
|
845
|
+
severity: ratio > 1.25 ? 'blocking' : 'warning',
|
|
846
|
+
rule_id: 'CONFLICT_POLY_SUM_EXCEEDS_BUDGET',
|
|
847
|
+
winning_layer_rank: 4,
|
|
848
|
+
winning_layer_id: 'layer_4_explicit_performance_and_resource_budgets',
|
|
849
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
850
|
+
summary: `Total object triangle budget (${totalObjectTriangles.toLocaleString()} tris) exceeds optimization_and_budgets.max_triangles (${spec.optimization_and_budgets.max_triangles.toLocaleString()} tris, ${(ratio * 100).toFixed(0)}% of budget).`,
|
|
851
|
+
affected_skills: ['polycount-budget-checker', 'mobile-glb-budget'],
|
|
852
|
+
knowledge_refs: [
|
|
853
|
+
'knowledge.triangle-draw-call-and-vram-budgets',
|
|
854
|
+
'knowledge.lod-hierarchy-and-decimation-strategy',
|
|
855
|
+
],
|
|
856
|
+
remediation:
|
|
857
|
+
'Reduce per-object poly_budget_triangles via Planar/Collapse Decimate with pinned UV seams, bake high-frequency detail into MikkTSpace normal maps, or raise max_triangles for non-mobile tiers.',
|
|
858
|
+
});
|
|
859
|
+
}
|
|
860
|
+
|
|
861
|
+
// 10. Camera far/near clip ratio > 100,000:1 (warning)
|
|
862
|
+
const clipRatio = spec.camera_and_framing.clip_end_m / spec.camera_and_framing.clip_start_m;
|
|
863
|
+
if (clipRatio > 100000) {
|
|
864
|
+
conflicts.push({
|
|
865
|
+
conflict_id: 'conflict.camera-clip-ratio-z-fighting',
|
|
866
|
+
severity: 'warning',
|
|
867
|
+
rule_id: 'CONFLICT_CAMERA_CLIP_RATIO_Z_FIGHTING',
|
|
868
|
+
winning_layer_rank: 7,
|
|
869
|
+
winning_layer_id: 'layer_7_skill_level_heuristics',
|
|
870
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
871
|
+
summary: `Camera clip_end_m / clip_start_m ratio (${Math.round(clipRatio).toLocaleString()}:1) exceeds the safe 100,000:1 depth precision threshold and risks coplanar Z-fighting flicker.`,
|
|
872
|
+
affected_skills: ['camera-composition', 'composition-quality-checker'],
|
|
873
|
+
knowledge_refs: ['knowledge.physically-based-camera-lens-and-dof'],
|
|
874
|
+
remediation:
|
|
875
|
+
'Raise camera_and_framing.clip_start_m (>= 0.01m - 0.1m) and lower clip_end_m to tightly bound the actual scene extents.',
|
|
876
|
+
});
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
// 11. Scan noise / non-manifold source mesh requires cleanup gate (warning)
|
|
880
|
+
const noisyObjects = spec.objects_and_subjects.filter((o) => o.has_non_manifold_or_scan_noise);
|
|
881
|
+
if (noisyObjects.length > 0) {
|
|
882
|
+
conflicts.push({
|
|
883
|
+
conflict_id: 'conflict.scan-noise-requires-cleanup-gate',
|
|
884
|
+
severity: 'warning',
|
|
885
|
+
rule_id: 'CONFLICT_SCAN_NOISE_REQUIRES_CLEANUP_GATE',
|
|
886
|
+
winning_layer_rank: 1,
|
|
887
|
+
winning_layer_id: 'layer_1_hard_laws_and_safety',
|
|
888
|
+
losing_layer_id: 'layer_6_domain_recipe_defaults',
|
|
889
|
+
summary: `Object(s) [${noisyObjects.map((o) => o.id).join(', ')}] flag has_non_manifold_or_scan_noise: true. UV unwrapping, normal baking, and Booleans will fail unless preceded by manifold cleanup.`,
|
|
890
|
+
affected_skills: ['scene-readiness', 'pre-handoff-verification'],
|
|
891
|
+
knowledge_refs: ['knowledge.mesh-manifold-normals-and-scale-hygiene'],
|
|
892
|
+
remediation:
|
|
893
|
+
'Execute scene-readiness manifold cleanup (Merge by Distance, Delete Loose, Fill Holes, Recalculate Outside Normals) before stage 5 material/UV baking.',
|
|
894
|
+
});
|
|
895
|
+
}
|
|
896
|
+
|
|
897
|
+
// 12. Hybrid Cycles offline render + real-time GLB dual-branch notice (informational)
|
|
898
|
+
const hasOfflineRender = spec.deliverables.formats.some((f) =>
|
|
899
|
+
['png_still', 'exr_multilayer'].includes(f),
|
|
900
|
+
);
|
|
901
|
+
if (spec.render_and_color.engine === 'CYCLES' && hasOfflineRender && deliversStandardGlb) {
|
|
902
|
+
conflicts.push({
|
|
903
|
+
conflict_id: 'conflict.hybrid-cycles-and-web-glb-dual-branch',
|
|
904
|
+
severity: 'informational',
|
|
905
|
+
rule_id: 'CONFLICT_HYBRID_CYCLES_AND_MOBILE_GLB',
|
|
906
|
+
winning_layer_rank: 2,
|
|
907
|
+
winning_layer_id: 'layer_2_target_delivery_format_and_spec',
|
|
908
|
+
losing_layer_id: 'layer_6_domain_recipe_defaults',
|
|
909
|
+
summary:
|
|
910
|
+
'SceneSpec targets both offline Cycles AgX rendering and standard web GLB export. Harmonizer schedules a dual-branch execution plan: full Cycles AgX lighting for still renders, and baked Principled BSDF PBR + KTX2/Draco for GLB handoff.',
|
|
911
|
+
affected_skills: [
|
|
912
|
+
'cycles-vs-eevee-decision',
|
|
913
|
+
'color-management-decision',
|
|
914
|
+
'glb-web-handoff',
|
|
915
|
+
],
|
|
916
|
+
knowledge_refs: [
|
|
917
|
+
'knowledge.agx-filmic-color-management-and-cycles-eevee',
|
|
918
|
+
'knowledge.threejs-r3f-tone-mapping-and-environment-parity',
|
|
919
|
+
],
|
|
920
|
+
remediation:
|
|
921
|
+
'Maintain Principled BSDF v2 energy-conserving materials and match AgX tone mapping + HDRI environment lighting in the target Three.js/R3F viewer.',
|
|
922
|
+
});
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
// 13. Path-specific Blender version floor enforcement (Layer 3: runtime & version limits)
|
|
926
|
+
const vBounds = extractBlenderVersionBounds(spec.blender_version_target);
|
|
927
|
+
const preferredPath = spec.runtime_preference?.preferred_path;
|
|
928
|
+
if (
|
|
929
|
+
preferredPath === 'path-1-official-blender-lab-mcp' &&
|
|
930
|
+
((vBounds.recVer !== null && vBounds.recVer < 501) ||
|
|
931
|
+
(vBounds.effectiveMaxVer !== null && vBounds.effectiveMaxVer < 501))
|
|
932
|
+
) {
|
|
933
|
+
conflicts.push({
|
|
934
|
+
conflict_id: 'conflict.runtime-path-1-blender-version-floor',
|
|
935
|
+
severity: 'blocking',
|
|
936
|
+
rule_id: 'CONFLICT_RUNTIME_PATH_1_BLENDER_VERSION_FLOOR',
|
|
937
|
+
winning_layer_rank: 3,
|
|
938
|
+
winning_layer_id: 'layer_3_runtime_and_blender_version_limits',
|
|
939
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
940
|
+
summary: `SceneSpec selects Path 1 (Official Blender Lab MCP) with blender_version_target recommended="${spec.blender_version_target.recommended}" (tested_range="${spec.blender_version_target.tested_range}"), which is below the mandatory Blender 5.1+ floor required by the official Blender Lab MCP add-on manifest.`,
|
|
941
|
+
affected_skills: ['runtime-path-picker', 'runtime-readiness', 'path-one-host-outline'],
|
|
942
|
+
knowledge_refs: ['knowledge.mesh-manifold-normals-and-scale-hygiene'],
|
|
943
|
+
remediation:
|
|
944
|
+
'Upgrade blender_version_target.recommended / tested_range to Blender 5.1+ for Path 1 Official Blender Lab MCP, or switch runtime_preference.preferred_path to "path-2-community-mcp-for-blender" (supports Blender 3.0+) or "cli-appendix-headless".',
|
|
945
|
+
});
|
|
946
|
+
} else if (
|
|
947
|
+
(preferredPath === 'path-2-community-mcp-for-blender' ||
|
|
948
|
+
preferredPath === 'cli-appendix-headless') &&
|
|
949
|
+
((vBounds.recVer !== null && vBounds.recVer < 300) ||
|
|
950
|
+
(vBounds.effectiveMaxVer !== null && vBounds.effectiveMaxVer < 300) ||
|
|
951
|
+
(vBounds.minVer !== null && vBounds.minVer < 300))
|
|
952
|
+
) {
|
|
953
|
+
conflicts.push({
|
|
954
|
+
conflict_id: 'conflict.runtime-path-2-blender-version-floor',
|
|
955
|
+
severity: 'blocking',
|
|
956
|
+
rule_id: 'CONFLICT_RUNTIME_PATH_2_BLENDER_VERSION_FLOOR',
|
|
957
|
+
winning_layer_rank: 3,
|
|
958
|
+
winning_layer_id: 'layer_3_runtime_and_blender_version_limits',
|
|
959
|
+
losing_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
960
|
+
summary: `SceneSpec selects ${preferredPath} with blender_version_target min="${spec.blender_version_target.min}" / recommended="${spec.blender_version_target.recommended}", which is below the Blender 3.0+ floor supported by Path 2 community mcp-for-blender and the CLI appendix.`,
|
|
961
|
+
affected_skills: ['runtime-path-picker', 'runtime-readiness'],
|
|
962
|
+
knowledge_refs: ['knowledge.mesh-manifold-normals-and-scale-hygiene'],
|
|
963
|
+
remediation:
|
|
964
|
+
'Target Blender 3.0+ (recommended 3.6 LTS - 5.1+) when using Path 2 community mcp-for-blender or CLI appendix headless execution.',
|
|
965
|
+
});
|
|
966
|
+
}
|
|
967
|
+
|
|
968
|
+
return conflicts;
|
|
969
|
+
}
|
|
970
|
+
|
|
971
|
+
/**
|
|
972
|
+
* Compiles a deterministic ExecutionPlan from a validated SceneSpec.
|
|
973
|
+
*/
|
|
974
|
+
export function compileExecutionPlan(specOrPath, options = {}) {
|
|
975
|
+
const repoRoot = options.repoRoot || DEFAULT_REPO_ROOT;
|
|
976
|
+
const projectDir = options.projectDir || null;
|
|
977
|
+
const catalogPaths = resolveCatalogPaths(repoRoot, projectDir);
|
|
978
|
+
|
|
979
|
+
const specValidation = validateSceneSpec(specOrPath, { repoRoot, projectDir });
|
|
980
|
+
if (!specValidation.valid) {
|
|
981
|
+
return {
|
|
982
|
+
ok: false,
|
|
983
|
+
validation: specValidation,
|
|
984
|
+
plan: null,
|
|
985
|
+
runtime_status: 'Not Run',
|
|
986
|
+
artifact_status: 'Not Produced',
|
|
987
|
+
};
|
|
988
|
+
}
|
|
989
|
+
|
|
990
|
+
const spec = specValidation.spec || loadInputJson(specOrPath).data;
|
|
991
|
+
const knowledgeCatalog = readJsonFile(catalogPaths.knowledgeCatalogPath);
|
|
992
|
+
const recipeCatalog = readJsonFile(catalogPaths.recipeCatalogPath);
|
|
993
|
+
const planSchema = readJsonFile(path.join(catalogPaths.schemasDir, 'execution-plan.schema.json'));
|
|
994
|
+
|
|
995
|
+
const knowledgeById = new Map(knowledgeCatalog.records.map((r) => [r.id, r]));
|
|
996
|
+
const recipesById = new Map(recipeCatalog.recipes.map((r) => [r.id, r]));
|
|
997
|
+
|
|
998
|
+
let recipeResolution;
|
|
999
|
+
try {
|
|
1000
|
+
recipeResolution = resolveRecipesForSpec(spec, recipesById);
|
|
1001
|
+
} catch (err) {
|
|
1002
|
+
return {
|
|
1003
|
+
ok: false,
|
|
1004
|
+
validation: {
|
|
1005
|
+
...specValidation,
|
|
1006
|
+
valid: false,
|
|
1007
|
+
errors: [...specValidation.errors, err.message],
|
|
1008
|
+
},
|
|
1009
|
+
plan: null,
|
|
1010
|
+
runtime_status: 'Not Run',
|
|
1011
|
+
artifact_status: 'Not Produced',
|
|
1012
|
+
};
|
|
1013
|
+
}
|
|
1014
|
+
const conflicts = detectConflicts(spec);
|
|
1015
|
+
|
|
1016
|
+
const blockingCount = conflicts.filter((c) => c.severity === 'blocking').length;
|
|
1017
|
+
const warningCount = conflicts.filter((c) => c.severity === 'warning').length;
|
|
1018
|
+
const infoCount = conflicts.filter((c) => c.severity === 'informational').length;
|
|
1019
|
+
|
|
1020
|
+
const status =
|
|
1021
|
+
blockingCount > 0 ? 'blocked' : warningCount > 0 ? 'ready_with_warnings' : 'ready';
|
|
1022
|
+
const isPlanningOnlyPath =
|
|
1023
|
+
spec.runtime_preference.preferred_path === 'unconfigured-planning-only';
|
|
1024
|
+
const canProceedToRuntime = blockingCount === 0 && !isPlanningOnlyPath;
|
|
1025
|
+
|
|
1026
|
+
const runtimeSkillMap = {
|
|
1027
|
+
'path-1-official-blender-lab-mcp': 'path-one-host-outline',
|
|
1028
|
+
'path-2-community-mcp-for-blender': 'runtime-path-picker',
|
|
1029
|
+
'cli-appendix-headless': 'cli-appendix-job-outline',
|
|
1030
|
+
'unconfigured-planning-only': 'runtime-setup',
|
|
1031
|
+
};
|
|
1032
|
+
const selectedRuntimeSkill =
|
|
1033
|
+
runtimeSkillMap[spec.runtime_preference.preferred_path] || 'runtime-path-picker';
|
|
1034
|
+
|
|
1035
|
+
const primaryRec = recipesById.get(recipeResolution.primary_recipe_id);
|
|
1036
|
+
const primaryPlannerSkill =
|
|
1037
|
+
primaryRec && Array.isArray(primaryRec.required_skill_ids)
|
|
1038
|
+
? primaryRec.required_skill_ids.find((s) =>
|
|
1039
|
+
[
|
|
1040
|
+
'product-hero-scene-planner',
|
|
1041
|
+
'environment-shot',
|
|
1042
|
+
'interior-scene',
|
|
1043
|
+
'character-portrait',
|
|
1044
|
+
'product-grid-scene-planner',
|
|
1045
|
+
].includes(s),
|
|
1046
|
+
)
|
|
1047
|
+
: null;
|
|
1048
|
+
|
|
1049
|
+
const deliversGlb = spec.deliverables.formats.some((f) =>
|
|
1050
|
+
['glb_web_standard', 'gltf_extended'].includes(f),
|
|
1051
|
+
);
|
|
1052
|
+
const deliversRender = spec.deliverables.formats.some((f) =>
|
|
1053
|
+
['png_still', 'exr_multilayer', 'mp4_turntable'].includes(f),
|
|
1054
|
+
);
|
|
1055
|
+
|
|
1056
|
+
const stages = [
|
|
1057
|
+
{
|
|
1058
|
+
stage_index: 1,
|
|
1059
|
+
stage_id: 'discover',
|
|
1060
|
+
stage_name: 'Discover & Scope Intent',
|
|
1061
|
+
skills: ['blender-brainstorming', 'workflow-stage-router', 'scope-guard'],
|
|
1062
|
+
knowledge_refs: [
|
|
1063
|
+
'knowledge.mesh-manifold-normals-and-scale-hygiene',
|
|
1064
|
+
'knowledge.modular-architectural-grid-and-metric-scale',
|
|
1065
|
+
],
|
|
1066
|
+
entry_criteria: 'Structured SceneSpec validated against schemas/scene-spec.schema.json.',
|
|
1067
|
+
exit_gate: 'Scope bounded to supported Blender/glTF capabilities with zero out-of-scope DCC assumptions.',
|
|
1068
|
+
},
|
|
1069
|
+
{
|
|
1070
|
+
stage_index: 2,
|
|
1071
|
+
stage_id: 'define',
|
|
1072
|
+
stage_name: 'Define Brief, Budgets & Acceptance Criteria',
|
|
1073
|
+
skills: [
|
|
1074
|
+
'intent-to-3d-brief-writer',
|
|
1075
|
+
'acceptance-criteria-builder',
|
|
1076
|
+
'polycount-budget-checker',
|
|
1077
|
+
...(spec.optimization_and_budgets.target_tier === 'mobile_web' ? ['mobile-glb-budget'] : []),
|
|
1078
|
+
],
|
|
1079
|
+
knowledge_refs: [
|
|
1080
|
+
'knowledge.triangle-draw-call-and-vram-budgets',
|
|
1081
|
+
'knowledge.gltf-2-coordinate-system-and-transform-conventions',
|
|
1082
|
+
],
|
|
1083
|
+
entry_criteria: 'Primary goal and target platform budgets declared.',
|
|
1084
|
+
exit_gate: 'Measurable triangle, draw-call, VRAM, and visual acceptance criteria locked.',
|
|
1085
|
+
},
|
|
1086
|
+
{
|
|
1087
|
+
stage_index: 3,
|
|
1088
|
+
stage_id: 'plan',
|
|
1089
|
+
stage_name: 'Harmonize Recipes, Camera, Lighting & Render Decisions',
|
|
1090
|
+
skills: [
|
|
1091
|
+
'recipe-fit-assessor',
|
|
1092
|
+
'blender-recipe-decomposer',
|
|
1093
|
+
...(primaryPlannerSkill ? [primaryPlannerSkill] : []),
|
|
1094
|
+
'camera-composition',
|
|
1095
|
+
'lighting-material-plan',
|
|
1096
|
+
'cycles-vs-eevee-decision',
|
|
1097
|
+
'color-management-decision',
|
|
1098
|
+
'resolution-aspect-decision',
|
|
1099
|
+
'output-format-decision',
|
|
1100
|
+
],
|
|
1101
|
+
knowledge_refs: [
|
|
1102
|
+
'knowledge.physically-based-camera-lens-and-dof',
|
|
1103
|
+
'knowledge.three-point-and-hdri-studio-lighting',
|
|
1104
|
+
'knowledge.principled-bsdf-v2-energy-conserving-pbr',
|
|
1105
|
+
'knowledge.agx-filmic-color-management-and-cycles-eevee',
|
|
1106
|
+
],
|
|
1107
|
+
entry_criteria: 'Acceptance criteria locked and recipes decomposed.',
|
|
1108
|
+
exit_gate: 'Zero blocking cross-skill conflicts in ExecutionPlan.',
|
|
1109
|
+
},
|
|
1110
|
+
{
|
|
1111
|
+
stage_index: 4,
|
|
1112
|
+
stage_id: 'source',
|
|
1113
|
+
stage_name: 'Source Assets, Check Readiness & Verify Runtime Path',
|
|
1114
|
+
skills: [
|
|
1115
|
+
'asset-discovery',
|
|
1116
|
+
'asset-license-checker',
|
|
1117
|
+
'asset-style-check',
|
|
1118
|
+
'asset-fallback-strategy',
|
|
1119
|
+
'scene-readiness',
|
|
1120
|
+
'runtime-path-picker',
|
|
1121
|
+
'runtime-readiness',
|
|
1122
|
+
selectedRuntimeSkill,
|
|
1123
|
+
],
|
|
1124
|
+
knowledge_refs: [
|
|
1125
|
+
'knowledge.mesh-manifold-normals-and-scale-hygiene',
|
|
1126
|
+
'knowledge.modular-architectural-grid-and-metric-scale',
|
|
1127
|
+
],
|
|
1128
|
+
entry_criteria: 'Harmonized ExecutionPlan status is ready or ready_with_warnings.',
|
|
1129
|
+
exit_gate: 'All source assets pass scale/manifold readiness and runtime smoke check is recorded.',
|
|
1130
|
+
},
|
|
1131
|
+
{
|
|
1132
|
+
stage_index: 5,
|
|
1133
|
+
stage_id: 'execute',
|
|
1134
|
+
stage_name: 'Execute Scene Assembly, Shading, Lighting & Baking',
|
|
1135
|
+
skills: [
|
|
1136
|
+
'stage-gates',
|
|
1137
|
+
'runtime-attempt-report',
|
|
1138
|
+
...(spec.animation_and_rigging.enabled ? ['glb-animation-handoff'] : []),
|
|
1139
|
+
...(deliversGlb ? ['glb-web-handoff'] : []),
|
|
1140
|
+
],
|
|
1141
|
+
knowledge_refs: [
|
|
1142
|
+
'knowledge.non-destructive-hard-surface-modifier-stack',
|
|
1143
|
+
'knowledge.uv-seam-placement-and-texel-density',
|
|
1144
|
+
'knowledge.normal-roughness-and-orm-channel-packing',
|
|
1145
|
+
...(spec.style_and_materials.bake_procedural_to_pbr
|
|
1146
|
+
? ['knowledge.shader-node-gltf-export-portability']
|
|
1147
|
+
: []),
|
|
1148
|
+
],
|
|
1149
|
+
entry_criteria: 'Stage 4 readiness gates passed with no blocking conflicts.',
|
|
1150
|
+
exit_gate: 'All scene mutations, UV/PBR bakes, and lighting setups recorded in runtime attempt report.',
|
|
1151
|
+
},
|
|
1152
|
+
{
|
|
1153
|
+
stage_index: 6,
|
|
1154
|
+
stage_id: 'verify',
|
|
1155
|
+
stage_name: 'Verify Quality Checkers & Pre-Handoff Gates',
|
|
1156
|
+
skills: [
|
|
1157
|
+
'composition-quality-checker',
|
|
1158
|
+
'lighting-quality-checker',
|
|
1159
|
+
'material-quality-checker',
|
|
1160
|
+
'preview-report',
|
|
1161
|
+
'pre-handoff-verification',
|
|
1162
|
+
],
|
|
1163
|
+
knowledge_refs: [
|
|
1164
|
+
'knowledge.environment-depth-layering-and-atmospheric-perspective',
|
|
1165
|
+
'knowledge.glb-binary-chunk-alignment-and-khronos-validation',
|
|
1166
|
+
...(deliversGlb ? ['knowledge.threejs-r3f-tone-mapping-and-environment-parity'] : []),
|
|
1167
|
+
],
|
|
1168
|
+
entry_criteria: 'Scene assembly and baking completed.',
|
|
1169
|
+
exit_gate: 'All composition, lighting, material, and Khronos validator checks pass.',
|
|
1170
|
+
},
|
|
1171
|
+
{
|
|
1172
|
+
stage_index: 7,
|
|
1173
|
+
stage_id: 'deliver',
|
|
1174
|
+
stage_name: 'Record Evidence Packets & Plain-Language Delivery',
|
|
1175
|
+
skills: [
|
|
1176
|
+
'render-export-evidence',
|
|
1177
|
+
'done-criteria',
|
|
1178
|
+
'plain-language-response',
|
|
1179
|
+
...(spec.deliverables.target_consumers.includes('threejs_r3f') ? ['r3f-component-plan'] : []),
|
|
1180
|
+
],
|
|
1181
|
+
knowledge_refs: [
|
|
1182
|
+
'knowledge.glb-binary-chunk-alignment-and-khronos-validation',
|
|
1183
|
+
'knowledge.texture-resolution-ktx2-and-draco-meshopt-compression',
|
|
1184
|
+
],
|
|
1185
|
+
entry_criteria: 'Pre-handoff verification passed.',
|
|
1186
|
+
exit_gate: 'Validated evidence packets recorded under docs/evals/ before any Verified claim.',
|
|
1187
|
+
},
|
|
1188
|
+
];
|
|
1189
|
+
|
|
1190
|
+
// Deduplicate stage skills & knowledge refs
|
|
1191
|
+
const allSkillSet = new Set();
|
|
1192
|
+
const allKnowledgeSet = new Set();
|
|
1193
|
+
|
|
1194
|
+
for (const step of recipeResolution.decomposed_sub_goals) {
|
|
1195
|
+
for (const s of step.skills) allSkillSet.add(s);
|
|
1196
|
+
for (const k of step.knowledge_refs) allKnowledgeSet.add(k);
|
|
1197
|
+
}
|
|
1198
|
+
for (const st of stages) {
|
|
1199
|
+
st.skills = [...new Set(st.skills)];
|
|
1200
|
+
st.knowledge_refs = [...new Set(st.knowledge_refs)];
|
|
1201
|
+
for (const s of st.skills) allSkillSet.add(s);
|
|
1202
|
+
for (const k of st.knowledge_refs) allKnowledgeSet.add(k);
|
|
1203
|
+
}
|
|
1204
|
+
for (const c of conflicts) {
|
|
1205
|
+
for (const s of c.affected_skills) allSkillSet.add(s);
|
|
1206
|
+
for (const k of c.knowledge_refs) allKnowledgeSet.add(k);
|
|
1207
|
+
}
|
|
1208
|
+
|
|
1209
|
+
const resolvedKnowledge = [...allKnowledgeSet]
|
|
1210
|
+
.map((id) => knowledgeById.get(id))
|
|
1211
|
+
.filter(Boolean)
|
|
1212
|
+
.map((k) => ({
|
|
1213
|
+
id: k.id,
|
|
1214
|
+
title: k.title,
|
|
1215
|
+
domain: k.domain,
|
|
1216
|
+
authority_level: k.evidence_status || 'version-checked',
|
|
1217
|
+
blender_versions: k.blender_versions || { minimum: '3.6 LTS', doc_checked_version: '5.2.3 LTS' },
|
|
1218
|
+
}));
|
|
1219
|
+
|
|
1220
|
+
const parameterDecisions = [
|
|
1221
|
+
{
|
|
1222
|
+
parameter: 'uv_packing_and_shader_portability',
|
|
1223
|
+
selected_value: deliversGlb
|
|
1224
|
+
? 'single_0_1_atlas_baked_principled_bsdf'
|
|
1225
|
+
: `${spec.style_and_materials.uv_packing}_${spec.style_and_materials.shader_workflow}`,
|
|
1226
|
+
winning_layer_rank: deliversGlb ? 2 : 5,
|
|
1227
|
+
winning_layer_id: deliversGlb
|
|
1228
|
+
? 'layer_2_target_delivery_format_and_spec'
|
|
1229
|
+
: 'layer_5_explicit_scene_spec_parameters',
|
|
1230
|
+
governing_id: deliversGlb
|
|
1231
|
+
? 'knowledge.shader-node-gltf-export-portability'
|
|
1232
|
+
: 'style_and_materials',
|
|
1233
|
+
rationale: deliversGlb
|
|
1234
|
+
? 'Khronos glTF 2.0 requires [0, 1] UV coordinates and baked Principled BSDF image textures.'
|
|
1235
|
+
: 'Uses explicit SceneSpec UV packing and shader workflow for offline rendering.',
|
|
1236
|
+
},
|
|
1237
|
+
{
|
|
1238
|
+
parameter: 'triangle_and_vram_budget',
|
|
1239
|
+
selected_value: `${spec.optimization_and_budgets.max_triangles} tris / ${spec.optimization_and_budgets.max_vram_mb} MB VRAM`,
|
|
1240
|
+
winning_layer_rank: 4,
|
|
1241
|
+
winning_layer_id: 'layer_4_explicit_performance_and_resource_budgets',
|
|
1242
|
+
governing_id: 'knowledge.triangle-draw-call-and-vram-budgets',
|
|
1243
|
+
rationale: `Enforces explicit ${spec.optimization_and_budgets.target_tier} budget ceiling via polycount-budget-checker.`,
|
|
1244
|
+
},
|
|
1245
|
+
{
|
|
1246
|
+
parameter: 'render_engine_and_color_transform',
|
|
1247
|
+
selected_value: `${spec.render_and_color.engine} (${spec.render_and_color.view_transform} / ${spec.render_and_color.look})`,
|
|
1248
|
+
winning_layer_rank: 5,
|
|
1249
|
+
winning_layer_id: 'layer_5_explicit_scene_spec_parameters',
|
|
1250
|
+
governing_id: 'knowledge.agx-filmic-color-management-and-cycles-eevee',
|
|
1251
|
+
rationale:
|
|
1252
|
+
'Preserves explicit SceneSpec engine and AgX color management with highlight desaturation rolloff.',
|
|
1253
|
+
},
|
|
1254
|
+
{
|
|
1255
|
+
parameter: 'runtime_execution_path',
|
|
1256
|
+
selected_value: spec.runtime_preference.preferred_path,
|
|
1257
|
+
winning_layer_rank: 3,
|
|
1258
|
+
winning_layer_id: 'layer_3_runtime_and_blender_version_limits',
|
|
1259
|
+
governing_id: selectedRuntimeSkill,
|
|
1260
|
+
rationale: `Routes execution planning through ${selectedRuntimeSkill} while keeping truth states at Not Run / Not Produced.`,
|
|
1261
|
+
},
|
|
1262
|
+
];
|
|
1263
|
+
|
|
1264
|
+
const stageGates = [
|
|
1265
|
+
{
|
|
1266
|
+
gate_id: 'gate.transform-and-manifold-readiness',
|
|
1267
|
+
stage_id: 'source',
|
|
1268
|
+
skill_id: 'scene-readiness',
|
|
1269
|
+
criterion:
|
|
1270
|
+
'All objects have applied unit scale [1, 1, 1], zero non-manifold holes, and consistent outward normals.',
|
|
1271
|
+
blocking: true,
|
|
1272
|
+
},
|
|
1273
|
+
{
|
|
1274
|
+
gate_id: 'gate.polycount-and-vram-budget',
|
|
1275
|
+
stage_id: 'define',
|
|
1276
|
+
skill_id: 'polycount-budget-checker',
|
|
1277
|
+
criterion: `Total triangles <= ${spec.optimization_and_budgets.max_triangles.toLocaleString()}, draw calls <= ${spec.optimization_and_budgets.max_draw_calls}, VRAM <= ${spec.optimization_and_budgets.max_vram_mb} MB.`,
|
|
1278
|
+
blocking: true,
|
|
1279
|
+
},
|
|
1280
|
+
{
|
|
1281
|
+
gate_id: 'gate.pbr-and-color-management-audit',
|
|
1282
|
+
stage_id: 'verify',
|
|
1283
|
+
skill_id: 'material-quality-checker',
|
|
1284
|
+
criterion:
|
|
1285
|
+
'Albedo within [0.04, 0.90] linear sRGB, Non-Color set on Normal/ORM maps, and AgX view transform verified.',
|
|
1286
|
+
blocking: true,
|
|
1287
|
+
},
|
|
1288
|
+
{
|
|
1289
|
+
gate_id: 'gate.evidence-before-done',
|
|
1290
|
+
stage_id: 'deliver',
|
|
1291
|
+
skill_id: 'done-criteria',
|
|
1292
|
+
criterion:
|
|
1293
|
+
'No runtime mutation, render, or GLB export claim may be marked Verified without a schema-valid evidence packet under docs/evals/.',
|
|
1294
|
+
blocking: true,
|
|
1295
|
+
},
|
|
1296
|
+
];
|
|
1297
|
+
|
|
1298
|
+
const requiredEvidencePackets = [
|
|
1299
|
+
{
|
|
1300
|
+
packet_type: 'runtime-smoke',
|
|
1301
|
+
governing_skill: 'runtime-readiness',
|
|
1302
|
+
schema_ref: 'schemas/evidence-packet.schema.json',
|
|
1303
|
+
required_before_claim: 'Verified runtime connection or scene inspection',
|
|
1304
|
+
default_truth_state: 'Not Run',
|
|
1305
|
+
},
|
|
1306
|
+
{
|
|
1307
|
+
packet_type: 'preview-check',
|
|
1308
|
+
governing_skill: 'preview-report',
|
|
1309
|
+
schema_ref: 'schemas/evidence-packet.schema.json',
|
|
1310
|
+
required_before_claim: 'Verified viewport/camera/lighting preview',
|
|
1311
|
+
default_truth_state: 'Not Produced',
|
|
1312
|
+
},
|
|
1313
|
+
];
|
|
1314
|
+
|
|
1315
|
+
if (deliversRender) {
|
|
1316
|
+
requiredEvidencePackets.push({
|
|
1317
|
+
packet_type: 'render-export',
|
|
1318
|
+
governing_skill: 'render-export-evidence',
|
|
1319
|
+
schema_ref: 'schemas/evidence-packet.schema.json',
|
|
1320
|
+
required_before_claim: 'Verified still render or turntable artifact',
|
|
1321
|
+
default_truth_state: 'Not Produced',
|
|
1322
|
+
});
|
|
1323
|
+
}
|
|
1324
|
+
if (deliversGlb) {
|
|
1325
|
+
requiredEvidencePackets.push({
|
|
1326
|
+
packet_type: 'glb-handoff',
|
|
1327
|
+
governing_skill: 'glb-web-handoff',
|
|
1328
|
+
schema_ref: 'schemas/evidence-packet.schema.json',
|
|
1329
|
+
required_before_claim: 'Verified Khronos glTF 2.0 GLB export and web handoff',
|
|
1330
|
+
default_truth_state: 'Not Produced',
|
|
1331
|
+
});
|
|
1332
|
+
}
|
|
1333
|
+
|
|
1334
|
+
const planSlug = spec.id.replace(/^scene-spec\./, '');
|
|
1335
|
+
const plan = {
|
|
1336
|
+
schema_version: '1.0.0',
|
|
1337
|
+
plan_id: `plan.${planSlug}`,
|
|
1338
|
+
scene_spec_id: spec.id,
|
|
1339
|
+
scene_spec_title: spec.title,
|
|
1340
|
+
status,
|
|
1341
|
+
can_proceed_to_runtime: canProceedToRuntime,
|
|
1342
|
+
blender_version_target: spec.blender_version_target,
|
|
1343
|
+
runtime_preference: {
|
|
1344
|
+
preferred_path: spec.runtime_preference.preferred_path,
|
|
1345
|
+
allow_cli_fallback: spec.runtime_preference.allow_cli_fallback,
|
|
1346
|
+
selected_runtime_skill: selectedRuntimeSkill,
|
|
1347
|
+
},
|
|
1348
|
+
precedence_hierarchy: PRECEDENCE_HIERARCHY,
|
|
1349
|
+
recipe_resolution: recipeResolution,
|
|
1350
|
+
stages,
|
|
1351
|
+
resolved_skills: [...allSkillSet],
|
|
1352
|
+
resolved_knowledge: resolvedKnowledge,
|
|
1353
|
+
parameter_decisions: parameterDecisions,
|
|
1354
|
+
conflicts,
|
|
1355
|
+
conflict_summary: {
|
|
1356
|
+
blocking_count: blockingCount,
|
|
1357
|
+
warning_count: warningCount,
|
|
1358
|
+
informational_count: infoCount,
|
|
1359
|
+
total_count: conflicts.length,
|
|
1360
|
+
},
|
|
1361
|
+
stage_gates: stageGates,
|
|
1362
|
+
required_evidence_packets: requiredEvidencePackets,
|
|
1363
|
+
truth_states: {
|
|
1364
|
+
runtime_status: 'Not Run',
|
|
1365
|
+
artifact_status: 'Not Produced',
|
|
1366
|
+
evidence_gate_enforced: true,
|
|
1367
|
+
},
|
|
1368
|
+
};
|
|
1369
|
+
|
|
1370
|
+
const ajv = new Ajv2020({ allErrors: true, strict: false });
|
|
1371
|
+
const validatePlan = ajv.compile(planSchema);
|
|
1372
|
+
if (!validatePlan(plan)) {
|
|
1373
|
+
throw new Error(
|
|
1374
|
+
`Compiled ExecutionPlan failed schema validation: ${formatAjvErrors(validatePlan.errors).join('; ')}`,
|
|
1375
|
+
);
|
|
1376
|
+
}
|
|
1377
|
+
|
|
1378
|
+
return {
|
|
1379
|
+
ok: true,
|
|
1380
|
+
catalog_source_mode: catalogPaths.sourceMode,
|
|
1381
|
+
validation: specValidation,
|
|
1382
|
+
plan,
|
|
1383
|
+
runtime_status: 'Not Run',
|
|
1384
|
+
artifact_status: 'Not Produced',
|
|
1385
|
+
};
|
|
1386
|
+
}
|
|
1387
|
+
|
|
1388
|
+
/**
|
|
1389
|
+
* Validates and inspects an existing ExecutionPlan JSON object or file,
|
|
1390
|
+
* enforcing both JSON Schema Draft 2020-12 and cross-layer semantic invariants.
|
|
1391
|
+
*/
|
|
1392
|
+
export function inspectExecutionPlan(planOrPath, options = {}) {
|
|
1393
|
+
const repoRoot = options.repoRoot || DEFAULT_REPO_ROOT;
|
|
1394
|
+
const projectDir = options.projectDir || null;
|
|
1395
|
+
const catalogPaths = resolveCatalogPaths(repoRoot, projectDir);
|
|
1396
|
+
const { schemasDir, knowledgeCatalogPath, recipeCatalogPath, skillsPath, sourceMode } =
|
|
1397
|
+
catalogPaths;
|
|
1398
|
+
const planSchema = readJsonFile(path.join(schemasDir, 'execution-plan.schema.json'));
|
|
1399
|
+
|
|
1400
|
+
let plan;
|
|
1401
|
+
try {
|
|
1402
|
+
plan = loadInputJson(planOrPath).data;
|
|
1403
|
+
} catch (err) {
|
|
1404
|
+
return {
|
|
1405
|
+
valid: false,
|
|
1406
|
+
errors: [err.message],
|
|
1407
|
+
plan: null,
|
|
1408
|
+
runtime_status: 'Not Run',
|
|
1409
|
+
artifact_status: 'Not Produced',
|
|
1410
|
+
};
|
|
1411
|
+
}
|
|
1412
|
+
|
|
1413
|
+
const ajv = new Ajv2020({ allErrors: true, strict: false });
|
|
1414
|
+
const validate = ajv.compile(planSchema);
|
|
1415
|
+
const errors = [];
|
|
1416
|
+
if (!validate(plan)) {
|
|
1417
|
+
for (const msg of formatAjvErrors(validate.errors)) {
|
|
1418
|
+
errors.push(`execution-plan schema error: ${msg}`);
|
|
1419
|
+
}
|
|
1420
|
+
}
|
|
1421
|
+
|
|
1422
|
+
// Load canonical catalogs for semantic invariant verification (Defect 2C)
|
|
1423
|
+
let knowledgeById = new Map();
|
|
1424
|
+
let recipesById = new Map();
|
|
1425
|
+
let canonicalSkillIds = new Set();
|
|
1426
|
+
try {
|
|
1427
|
+
const knowledgeCatalog = readJsonFile(knowledgeCatalogPath);
|
|
1428
|
+
const recipeCatalog = readJsonFile(recipeCatalogPath);
|
|
1429
|
+
const skillsData = readJsonFile(skillsPath);
|
|
1430
|
+
knowledgeById = new Map((knowledgeCatalog.records || []).map((r) => [r.id, r]));
|
|
1431
|
+
recipesById = new Map((recipeCatalog.recipes || []).map((r) => [r.id, r]));
|
|
1432
|
+
canonicalSkillIds = new Set((skillsData.skills || []).map((s) => s.id));
|
|
1433
|
+
} catch (err) {
|
|
1434
|
+
errors.push(`Failed to load canonical catalogs for plan inspection: ${err.message}`);
|
|
1435
|
+
}
|
|
1436
|
+
|
|
1437
|
+
if (plan && typeof plan === 'object') {
|
|
1438
|
+
// 1. Conflict counts and status consistency invariants
|
|
1439
|
+
const conflicts = Array.isArray(plan.conflicts) ? plan.conflicts : [];
|
|
1440
|
+
const seenConflictIds = new Set();
|
|
1441
|
+
for (const c of conflicts) {
|
|
1442
|
+
if (c && c.conflict_id) {
|
|
1443
|
+
if (seenConflictIds.has(c.conflict_id)) {
|
|
1444
|
+
errors.push(`Duplicate conflict_id in conflicts[]: "${c.conflict_id}"`);
|
|
1445
|
+
}
|
|
1446
|
+
seenConflictIds.add(c.conflict_id);
|
|
1447
|
+
}
|
|
1448
|
+
}
|
|
1449
|
+
|
|
1450
|
+
const actualBlocking = conflicts.filter((c) => c?.severity === 'blocking').length;
|
|
1451
|
+
const actualWarning = conflicts.filter((c) => c?.severity === 'warning').length;
|
|
1452
|
+
const actualInfo = conflicts.filter((c) => c?.severity === 'informational').length;
|
|
1453
|
+
const actualTotal = conflicts.length;
|
|
1454
|
+
|
|
1455
|
+
if (plan.conflict_summary && typeof plan.conflict_summary === 'object') {
|
|
1456
|
+
if (plan.conflict_summary.blocking_count !== actualBlocking) {
|
|
1457
|
+
errors.push(
|
|
1458
|
+
`conflict_summary.blocking_count (${plan.conflict_summary.blocking_count}) does not match actual blocking conflicts (${actualBlocking}).`,
|
|
1459
|
+
);
|
|
1460
|
+
}
|
|
1461
|
+
if (plan.conflict_summary.warning_count !== actualWarning) {
|
|
1462
|
+
errors.push(
|
|
1463
|
+
`conflict_summary.warning_count (${plan.conflict_summary.warning_count}) does not match actual warning conflicts (${actualWarning}).`,
|
|
1464
|
+
);
|
|
1465
|
+
}
|
|
1466
|
+
if (plan.conflict_summary.informational_count !== actualInfo) {
|
|
1467
|
+
errors.push(
|
|
1468
|
+
`conflict_summary.informational_count (${plan.conflict_summary.informational_count}) does not match actual informational conflicts (${actualInfo}).`,
|
|
1469
|
+
);
|
|
1470
|
+
}
|
|
1471
|
+
if (plan.conflict_summary.total_count !== actualTotal) {
|
|
1472
|
+
errors.push(
|
|
1473
|
+
`conflict_summary.total_count (${plan.conflict_summary.total_count}) does not match actual conflicts length (${actualTotal}).`,
|
|
1474
|
+
);
|
|
1475
|
+
}
|
|
1476
|
+
}
|
|
1477
|
+
|
|
1478
|
+
const expectedStatus =
|
|
1479
|
+
actualBlocking > 0 ? 'blocked' : actualWarning > 0 ? 'ready_with_warnings' : 'ready';
|
|
1480
|
+
if (plan.status !== expectedStatus) {
|
|
1481
|
+
errors.push(
|
|
1482
|
+
`ExecutionPlan status "${plan.status}" contradicts conflicts (blocking=${actualBlocking}, warning=${actualWarning}; expected status="${expectedStatus}").`,
|
|
1483
|
+
);
|
|
1484
|
+
}
|
|
1485
|
+
|
|
1486
|
+
const isPlanningOnlyPath =
|
|
1487
|
+
plan.runtime_preference?.preferred_path === 'unconfigured-planning-only';
|
|
1488
|
+
const expectedCanProceed =
|
|
1489
|
+
actualBlocking === 0 && plan.status !== 'blocked' && !isPlanningOnlyPath;
|
|
1490
|
+
if (plan.can_proceed_to_runtime !== expectedCanProceed) {
|
|
1491
|
+
errors.push(
|
|
1492
|
+
`ExecutionPlan can_proceed_to_runtime (${plan.can_proceed_to_runtime}) contradicts plan readiness/runtime state (status="${plan.status}", blocking=${actualBlocking}, preferred_path="${plan.runtime_preference?.preferred_path}"; expected ${expectedCanProceed}).`,
|
|
1493
|
+
);
|
|
1494
|
+
}
|
|
1495
|
+
|
|
1496
|
+
// 2. Runtime path and version floor consistency
|
|
1497
|
+
const runtimeSkillMap = {
|
|
1498
|
+
'path-1-official-blender-lab-mcp': 'path-one-host-outline',
|
|
1499
|
+
'path-2-community-mcp-for-blender': 'runtime-path-picker',
|
|
1500
|
+
'cli-appendix-headless': 'cli-appendix-job-outline',
|
|
1501
|
+
'unconfigured-planning-only': 'runtime-setup',
|
|
1502
|
+
};
|
|
1503
|
+
const prefPath = plan.runtime_preference?.preferred_path;
|
|
1504
|
+
if (!prefPath || !Object.prototype.hasOwnProperty.call(runtimeSkillMap, prefPath)) {
|
|
1505
|
+
errors.push(
|
|
1506
|
+
`Invalid runtime_preference.preferred_path "${String(prefPath)}". Must be one of: ${Object.keys(runtimeSkillMap).join(', ')}.`,
|
|
1507
|
+
);
|
|
1508
|
+
} else if (plan.runtime_preference.selected_runtime_skill !== runtimeSkillMap[prefPath]) {
|
|
1509
|
+
errors.push(
|
|
1510
|
+
`runtime_preference.selected_runtime_skill "${plan.runtime_preference.selected_runtime_skill}" does not match preferred_path "${prefPath}" (expected "${runtimeSkillMap[prefPath]}").`,
|
|
1511
|
+
);
|
|
1512
|
+
}
|
|
1513
|
+
|
|
1514
|
+
if (plan.blender_version_target && typeof plan.blender_version_target === 'object') {
|
|
1515
|
+
const vBounds = extractBlenderVersionBounds(plan.blender_version_target);
|
|
1516
|
+
if (vBounds.minVer !== null && vBounds.recVer !== null && vBounds.minVer > vBounds.recVer) {
|
|
1517
|
+
errors.push(
|
|
1518
|
+
`blender_version_target.min (${plan.blender_version_target.min}) exceeds recommended (${plan.blender_version_target.recommended}).`,
|
|
1519
|
+
);
|
|
1520
|
+
}
|
|
1521
|
+
if (
|
|
1522
|
+
prefPath === 'path-1-official-blender-lab-mcp' &&
|
|
1523
|
+
((vBounds.recVer !== null && vBounds.recVer < 501) ||
|
|
1524
|
+
(vBounds.effectiveMaxVer !== null && vBounds.effectiveMaxVer < 501)) &&
|
|
1525
|
+
plan.status !== 'blocked'
|
|
1526
|
+
) {
|
|
1527
|
+
errors.push(
|
|
1528
|
+
`ExecutionPlan selects Path 1 Official Blender Lab MCP with Blender target below 5.1+ (${plan.blender_version_target.recommended}), but status is "${plan.status}" instead of "blocked".`,
|
|
1529
|
+
);
|
|
1530
|
+
}
|
|
1531
|
+
if (
|
|
1532
|
+
(prefPath === 'path-2-community-mcp-for-blender' ||
|
|
1533
|
+
prefPath === 'cli-appendix-headless') &&
|
|
1534
|
+
((vBounds.recVer !== null && vBounds.recVer < 300) ||
|
|
1535
|
+
(vBounds.effectiveMaxVer !== null && vBounds.effectiveMaxVer < 300) ||
|
|
1536
|
+
(vBounds.minVer !== null && vBounds.minVer < 300)) &&
|
|
1537
|
+
plan.status !== 'blocked'
|
|
1538
|
+
) {
|
|
1539
|
+
errors.push(
|
|
1540
|
+
`ExecutionPlan selects ${prefPath} with Blender target below 3.0+ (${plan.blender_version_target.recommended}), but status is "${plan.status}" instead of "blocked".`,
|
|
1541
|
+
);
|
|
1542
|
+
}
|
|
1543
|
+
}
|
|
1544
|
+
|
|
1545
|
+
// 3. Recipe resolution integrity against canonical recipe catalog
|
|
1546
|
+
const rr = plan.recipe_resolution;
|
|
1547
|
+
if (rr && typeof rr === 'object') {
|
|
1548
|
+
if (!rr.primary_recipe_id || !recipesById.has(rr.primary_recipe_id)) {
|
|
1549
|
+
errors.push(
|
|
1550
|
+
`Unresolved recipe_resolution.primary_recipe_id "${rr.primary_recipe_id}" in ${sourceMode} recipe catalog.`,
|
|
1551
|
+
);
|
|
1552
|
+
}
|
|
1553
|
+
const suppIds = Array.isArray(rr.supporting_recipe_ids) ? rr.supporting_recipe_ids : [];
|
|
1554
|
+
const seenSupp = new Set();
|
|
1555
|
+
for (const sid of suppIds) {
|
|
1556
|
+
if (!recipesById.has(sid)) {
|
|
1557
|
+
errors.push(
|
|
1558
|
+
`Unresolved recipe_resolution.supporting_recipe_ids entry "${sid}" in ${sourceMode} recipe catalog.`,
|
|
1559
|
+
);
|
|
1560
|
+
}
|
|
1561
|
+
if (sid === rr.primary_recipe_id) {
|
|
1562
|
+
errors.push(
|
|
1563
|
+
`recipe_resolution.supporting_recipe_ids must not duplicate primary_recipe_id "${sid}".`,
|
|
1564
|
+
);
|
|
1565
|
+
}
|
|
1566
|
+
if (seenSupp.has(sid)) {
|
|
1567
|
+
errors.push(`Duplicate recipe ID "${sid}" in recipe_resolution.supporting_recipe_ids.`);
|
|
1568
|
+
}
|
|
1569
|
+
seenSupp.add(sid);
|
|
1570
|
+
}
|
|
1571
|
+
|
|
1572
|
+
const subGoals = Array.isArray(rr.decomposed_sub_goals) ? rr.decomposed_sub_goals : [];
|
|
1573
|
+
if (subGoals.length > 0 && subGoals[0]?.recipe_id !== rr.primary_recipe_id) {
|
|
1574
|
+
errors.push(
|
|
1575
|
+
`recipe_resolution.decomposed_sub_goals[0].recipe_id ("${subGoals[0]?.recipe_id}") must match primary_recipe_id ("${rr.primary_recipe_id}").`,
|
|
1576
|
+
);
|
|
1577
|
+
}
|
|
1578
|
+
subGoals.forEach((sg, idx) => {
|
|
1579
|
+
if (sg.step_index !== idx + 1) {
|
|
1580
|
+
errors.push(
|
|
1581
|
+
`decomposed_sub_goals[${idx}].step_index (${sg.step_index}) must be sequential (${idx + 1}).`,
|
|
1582
|
+
);
|
|
1583
|
+
}
|
|
1584
|
+
if (!recipesById.has(sg.recipe_id)) {
|
|
1585
|
+
errors.push(
|
|
1586
|
+
`Unresolved decomposed_sub_goals[${idx}].recipe_id "${sg.recipe_id}" in ${sourceMode} recipe catalog.`,
|
|
1587
|
+
);
|
|
1588
|
+
}
|
|
1589
|
+
for (const sk of sg.skills || []) {
|
|
1590
|
+
if (!canonicalSkillIds.has(sk)) {
|
|
1591
|
+
errors.push(
|
|
1592
|
+
`Unknown skill "${sk}" in decomposed_sub_goals[${idx}].skills (not in canonical 48-skill registry).`,
|
|
1593
|
+
);
|
|
1594
|
+
}
|
|
1595
|
+
}
|
|
1596
|
+
for (const kr of sg.knowledge_refs || []) {
|
|
1597
|
+
if (!knowledgeById.has(kr)) {
|
|
1598
|
+
errors.push(
|
|
1599
|
+
`Unknown knowledge ref "${kr}" in decomposed_sub_goals[${idx}].knowledge_refs.`,
|
|
1600
|
+
);
|
|
1601
|
+
}
|
|
1602
|
+
}
|
|
1603
|
+
});
|
|
1604
|
+
}
|
|
1605
|
+
|
|
1606
|
+
// 4. Resolved skills & knowledge cross-reference integrity
|
|
1607
|
+
const resolvedSkillSet = new Set();
|
|
1608
|
+
if (Array.isArray(plan.resolved_skills)) {
|
|
1609
|
+
for (const sk of plan.resolved_skills) {
|
|
1610
|
+
if (resolvedSkillSet.has(sk)) {
|
|
1611
|
+
errors.push(`Duplicate skill ID "${sk}" in resolved_skills.`);
|
|
1612
|
+
}
|
|
1613
|
+
resolvedSkillSet.add(sk);
|
|
1614
|
+
if (!canonicalSkillIds.has(sk)) {
|
|
1615
|
+
errors.push(
|
|
1616
|
+
`Unknown skill ID "${sk}" in resolved_skills (not in canonical 48-skill registry).`,
|
|
1617
|
+
);
|
|
1618
|
+
}
|
|
1619
|
+
}
|
|
1620
|
+
}
|
|
1621
|
+
|
|
1622
|
+
const resolvedKnowledgeSet = new Set();
|
|
1623
|
+
if (Array.isArray(plan.resolved_knowledge)) {
|
|
1624
|
+
for (const kObj of plan.resolved_knowledge) {
|
|
1625
|
+
if (!kObj || !kObj.id) continue;
|
|
1626
|
+
if (resolvedKnowledgeSet.has(kObj.id)) {
|
|
1627
|
+
errors.push(`Duplicate knowledge ID "${kObj.id}" in resolved_knowledge.`);
|
|
1628
|
+
}
|
|
1629
|
+
resolvedKnowledgeSet.add(kObj.id);
|
|
1630
|
+
if (!knowledgeById.has(kObj.id)) {
|
|
1631
|
+
errors.push(
|
|
1632
|
+
`Unknown knowledge ID "${kObj.id}" in resolved_knowledge (not in canonical knowledge catalog).`,
|
|
1633
|
+
);
|
|
1634
|
+
}
|
|
1635
|
+
}
|
|
1636
|
+
}
|
|
1637
|
+
|
|
1638
|
+
// 5. 7-stage ordering and stage skill/knowledge references
|
|
1639
|
+
const expectedStages = [
|
|
1640
|
+
'discover',
|
|
1641
|
+
'define',
|
|
1642
|
+
'plan',
|
|
1643
|
+
'source',
|
|
1644
|
+
'execute',
|
|
1645
|
+
'verify',
|
|
1646
|
+
'deliver',
|
|
1647
|
+
];
|
|
1648
|
+
if (Array.isArray(plan.stages)) {
|
|
1649
|
+
plan.stages.forEach((st, idx) => {
|
|
1650
|
+
if (st.stage_index !== idx + 1) {
|
|
1651
|
+
errors.push(`stages[${idx}].stage_index (${st.stage_index}) must be ${idx + 1}.`);
|
|
1652
|
+
}
|
|
1653
|
+
if (st.stage_id !== expectedStages[idx]) {
|
|
1654
|
+
errors.push(
|
|
1655
|
+
`stages[${idx}].stage_id ("${st.stage_id}") must be "${expectedStages[idx]}" at stage_index ${idx + 1}.`,
|
|
1656
|
+
);
|
|
1657
|
+
}
|
|
1658
|
+
for (const sk of st.skills || []) {
|
|
1659
|
+
if (!canonicalSkillIds.has(sk)) {
|
|
1660
|
+
errors.push(`Unknown skill ID "${sk}" in stages[${idx}].skills.`);
|
|
1661
|
+
}
|
|
1662
|
+
if (!resolvedSkillSet.has(sk)) {
|
|
1663
|
+
errors.push(
|
|
1664
|
+
`Skill "${sk}" in stages[${idx}].skills is missing from plan.resolved_skills.`,
|
|
1665
|
+
);
|
|
1666
|
+
}
|
|
1667
|
+
}
|
|
1668
|
+
for (const kr of st.knowledge_refs || []) {
|
|
1669
|
+
if (!knowledgeById.has(kr)) {
|
|
1670
|
+
errors.push(`Unknown knowledge ID "${kr}" in stages[${idx}].knowledge_refs.`);
|
|
1671
|
+
}
|
|
1672
|
+
if (!resolvedKnowledgeSet.has(kr)) {
|
|
1673
|
+
errors.push(
|
|
1674
|
+
`Knowledge "${kr}" in stages[${idx}].knowledge_refs is missing from plan.resolved_knowledge.`,
|
|
1675
|
+
);
|
|
1676
|
+
}
|
|
1677
|
+
}
|
|
1678
|
+
});
|
|
1679
|
+
}
|
|
1680
|
+
|
|
1681
|
+
// 6. Stage gates, conflict references, and required evidence packets
|
|
1682
|
+
for (const gate of plan.stage_gates || []) {
|
|
1683
|
+
if (!canonicalSkillIds.has(gate.skill_id)) {
|
|
1684
|
+
errors.push(`Unknown skill_id "${gate.skill_id}" in stage_gates (${gate.gate_id}).`);
|
|
1685
|
+
}
|
|
1686
|
+
if (!expectedStages.includes(gate.stage_id)) {
|
|
1687
|
+
errors.push(`Invalid stage_id "${gate.stage_id}" in stage_gates (${gate.gate_id}).`);
|
|
1688
|
+
}
|
|
1689
|
+
}
|
|
1690
|
+
|
|
1691
|
+
for (const c of conflicts) {
|
|
1692
|
+
for (const sk of c.affected_skills || []) {
|
|
1693
|
+
if (!canonicalSkillIds.has(sk)) {
|
|
1694
|
+
errors.push(`Unknown affected_skill "${sk}" in conflict "${c.conflict_id}".`);
|
|
1695
|
+
}
|
|
1696
|
+
}
|
|
1697
|
+
for (const kr of c.knowledge_refs || []) {
|
|
1698
|
+
if (!knowledgeById.has(kr)) {
|
|
1699
|
+
errors.push(`Unknown knowledge_ref "${kr}" in conflict "${c.conflict_id}".`);
|
|
1700
|
+
}
|
|
1701
|
+
}
|
|
1702
|
+
}
|
|
1703
|
+
|
|
1704
|
+
const packetTypes = new Set();
|
|
1705
|
+
for (const pkt of plan.required_evidence_packets || []) {
|
|
1706
|
+
packetTypes.add(pkt.packet_type);
|
|
1707
|
+
if (!canonicalSkillIds.has(pkt.governing_skill)) {
|
|
1708
|
+
errors.push(
|
|
1709
|
+
`Unknown governing_skill "${pkt.governing_skill}" in required_evidence_packets (${pkt.packet_type}).`,
|
|
1710
|
+
);
|
|
1711
|
+
}
|
|
1712
|
+
}
|
|
1713
|
+
if (!packetTypes.has('runtime-smoke') || !packetTypes.has('preview-check')) {
|
|
1714
|
+
errors.push(
|
|
1715
|
+
`required_evidence_packets must include both "runtime-smoke" and "preview-check".`,
|
|
1716
|
+
);
|
|
1717
|
+
}
|
|
1718
|
+
|
|
1719
|
+
// 7. Truth-state invariants (Law 1: Evidence Before Done)
|
|
1720
|
+
if (
|
|
1721
|
+
!plan.truth_states ||
|
|
1722
|
+
plan.truth_states.runtime_status !== 'Not Run' ||
|
|
1723
|
+
plan.truth_states.artifact_status !== 'Not Produced' ||
|
|
1724
|
+
plan.truth_states.evidence_gate_enforced !== true
|
|
1725
|
+
) {
|
|
1726
|
+
errors.push(
|
|
1727
|
+
`ExecutionPlan truth_states must remain runtime_status="Not Run", artifact_status="Not Produced", evidence_gate_enforced=true.`,
|
|
1728
|
+
);
|
|
1729
|
+
}
|
|
1730
|
+
}
|
|
1731
|
+
|
|
1732
|
+
return {
|
|
1733
|
+
valid: errors.length === 0,
|
|
1734
|
+
errors,
|
|
1735
|
+
catalog_source_mode: sourceMode,
|
|
1736
|
+
plan_id: plan?.plan_id || null,
|
|
1737
|
+
scene_spec_id: plan?.scene_spec_id || null,
|
|
1738
|
+
status: plan?.status || null,
|
|
1739
|
+
can_proceed_to_runtime: Boolean(plan?.can_proceed_to_runtime),
|
|
1740
|
+
primary_recipe_id: plan?.recipe_resolution?.primary_recipe_id || null,
|
|
1741
|
+
supporting_recipe_ids: plan?.recipe_resolution?.supporting_recipe_ids || [],
|
|
1742
|
+
resolved_skill_count: Array.isArray(plan?.resolved_skills) ? plan.resolved_skills.length : 0,
|
|
1743
|
+
resolved_knowledge_count: Array.isArray(plan?.resolved_knowledge)
|
|
1744
|
+
? plan.resolved_knowledge.length
|
|
1745
|
+
: 0,
|
|
1746
|
+
conflict_summary: plan?.conflict_summary || null,
|
|
1747
|
+
conflicts: plan?.conflicts || [],
|
|
1748
|
+
plan,
|
|
1749
|
+
runtime_status: 'Not Run',
|
|
1750
|
+
artifact_status: 'Not Produced',
|
|
1751
|
+
};
|
|
1752
|
+
}
|
|
1753
|
+
|
|
1754
|
+
function formatPlanInspectionHumanReport(inspection) {
|
|
1755
|
+
if (!inspection.valid) {
|
|
1756
|
+
return [
|
|
1757
|
+
'# BlendOps ExecutionPlan Inspection',
|
|
1758
|
+
'Valid: No',
|
|
1759
|
+
...inspection.errors.map((e) => ` - ${e}`),
|
|
1760
|
+
'Runtime status: Not Run',
|
|
1761
|
+
'Artifact status: Not Produced',
|
|
1762
|
+
].join('\n');
|
|
1763
|
+
}
|
|
1764
|
+
const p = inspection.plan;
|
|
1765
|
+
const lines = [
|
|
1766
|
+
`# BlendOps ExecutionPlan — ${p.plan_id}`,
|
|
1767
|
+
`SceneSpec: ${p.scene_spec_id} (${p.scene_spec_title})`,
|
|
1768
|
+
`Status: ${p.status} (Can proceed to runtime: ${p.can_proceed_to_runtime ? 'Yes' : 'No — blocked by conflicts or unconfigured runtime path'})`,
|
|
1769
|
+
`Primary Recipe: ${p.recipe_resolution.primary_recipe_id}`,
|
|
1770
|
+
`Supporting Recipes: ${p.recipe_resolution.supporting_recipe_ids.join(', ') || 'none'}`,
|
|
1771
|
+
`Resolved Skills (${p.resolved_skills.length}): ${p.resolved_skills.join(', ')}`,
|
|
1772
|
+
`Resolved Knowledge Records (${p.resolved_knowledge.length}): ${p.resolved_knowledge.map((k) => k.id).join(', ')}`,
|
|
1773
|
+
`Conflicts: ${p.conflict_summary.total_count} total (${p.conflict_summary.blocking_count} blocking, ${p.conflict_summary.warning_count} warning, ${p.conflict_summary.informational_count} informational)`,
|
|
1774
|
+
];
|
|
1775
|
+
for (const c of p.conflicts) {
|
|
1776
|
+
lines.push(
|
|
1777
|
+
` - [${c.severity.toUpperCase()}] ${c.conflict_id} (${c.rule_id}, winning layer #${c.winning_layer_rank} ${c.winning_layer_id}): ${c.summary}`,
|
|
1778
|
+
` Remediation: ${c.remediation}`,
|
|
1779
|
+
);
|
|
1780
|
+
}
|
|
1781
|
+
lines.push(
|
|
1782
|
+
`Required Evidence Packets: ${p.required_evidence_packets.map((e) => e.packet_type).join(', ')}`,
|
|
1783
|
+
`Runtime status: ${p.truth_states.runtime_status}`,
|
|
1784
|
+
`Artifact status: ${p.truth_states.artifact_status}`,
|
|
1785
|
+
);
|
|
1786
|
+
return lines.join('\n');
|
|
1787
|
+
}
|
|
1788
|
+
|
|
1789
|
+
/**
|
|
1790
|
+
* CLI handler for `scene-spec-validate`, `plan-compile`, and `plan-inspect`.
|
|
1791
|
+
*/
|
|
1792
|
+
export function runPlanCliSubcommand(argv, options = {}) {
|
|
1793
|
+
const repoRoot = options.repoRoot || DEFAULT_REPO_ROOT;
|
|
1794
|
+
const sub = argv[0];
|
|
1795
|
+
const rest = argv.slice(1);
|
|
1796
|
+
const asJson = rest.includes('--json');
|
|
1797
|
+
|
|
1798
|
+
let projectDir = options.projectDir || null;
|
|
1799
|
+
let outPath = null;
|
|
1800
|
+
const positional = [];
|
|
1801
|
+
|
|
1802
|
+
for (let i = 0; i < rest.length; i++) {
|
|
1803
|
+
const arg = rest[i];
|
|
1804
|
+
if (arg === '--json') continue;
|
|
1805
|
+
if (arg === '--project' && rest[i + 1]) {
|
|
1806
|
+
projectDir = rest[++i];
|
|
1807
|
+
} else if (arg === '--out' && rest[i + 1]) {
|
|
1808
|
+
outPath = rest[++i];
|
|
1809
|
+
} else if (!arg.startsWith('--')) {
|
|
1810
|
+
positional.push(arg);
|
|
1811
|
+
}
|
|
1812
|
+
}
|
|
1813
|
+
|
|
1814
|
+
const targetPath = positional[0];
|
|
1815
|
+
if (!targetPath) {
|
|
1816
|
+
return {
|
|
1817
|
+
ok: false,
|
|
1818
|
+
exitCode: 1,
|
|
1819
|
+
report: `Missing required file path argument for ${sub}.\nRuntime status: Not Run\nArtifact status: Not Produced`,
|
|
1820
|
+
runtimeStatus: 'Not Run',
|
|
1821
|
+
artifactStatus: 'Not Produced',
|
|
1822
|
+
};
|
|
1823
|
+
}
|
|
1824
|
+
|
|
1825
|
+
if (sub === 'scene-spec-validate') {
|
|
1826
|
+
const res = validateSceneSpec(targetPath, { repoRoot, projectDir });
|
|
1827
|
+
const report = asJson
|
|
1828
|
+
? JSON.stringify(res, null, 2)
|
|
1829
|
+
: [
|
|
1830
|
+
`# BlendOps SceneSpec Validation`,
|
|
1831
|
+
`Spec ID: ${res.spec_id || 'unknown'}`,
|
|
1832
|
+
`Valid: ${res.valid ? 'Yes' : 'No'}`,
|
|
1833
|
+
`Errors: ${res.errors.length}`,
|
|
1834
|
+
...res.errors.map((e) => ` - ${e}`),
|
|
1835
|
+
`Warnings: ${res.warnings.length}`,
|
|
1836
|
+
...res.warnings.map((w) => ` - ${w}`),
|
|
1837
|
+
`Runtime status: Not Run`,
|
|
1838
|
+
`Artifact status: Not Produced`,
|
|
1839
|
+
].join('\n');
|
|
1840
|
+
return {
|
|
1841
|
+
ok: res.valid,
|
|
1842
|
+
exitCode: res.valid ? 0 : 1,
|
|
1843
|
+
report,
|
|
1844
|
+
data: res,
|
|
1845
|
+
runtimeStatus: 'Not Run',
|
|
1846
|
+
artifactStatus: 'Not Produced',
|
|
1847
|
+
};
|
|
1848
|
+
}
|
|
1849
|
+
|
|
1850
|
+
if (sub === 'plan-compile') {
|
|
1851
|
+
if (outPath) {
|
|
1852
|
+
const outCheck = validateSafeCliOutFilePath(outPath, { repoRoot, projectDir });
|
|
1853
|
+
if (!outCheck.valid) {
|
|
1854
|
+
const errPayload = {
|
|
1855
|
+
ok: false,
|
|
1856
|
+
error: outCheck.error,
|
|
1857
|
+
runtime_status: 'Not Run',
|
|
1858
|
+
artifact_status: 'Not Produced',
|
|
1859
|
+
};
|
|
1860
|
+
return {
|
|
1861
|
+
ok: false,
|
|
1862
|
+
exitCode: 1,
|
|
1863
|
+
report: asJson
|
|
1864
|
+
? JSON.stringify(errPayload, null, 2)
|
|
1865
|
+
: `# BlendOps Plan Compilation Failed (Unsafe --out Path)\n - ${outCheck.error}\nRuntime status: Not Run\nArtifact status: Not Produced`,
|
|
1866
|
+
data: errPayload,
|
|
1867
|
+
runtimeStatus: 'Not Run',
|
|
1868
|
+
artifactStatus: 'Not Produced',
|
|
1869
|
+
};
|
|
1870
|
+
}
|
|
1871
|
+
}
|
|
1872
|
+
|
|
1873
|
+
const compiled = compileExecutionPlan(targetPath, { repoRoot, projectDir });
|
|
1874
|
+
if (!compiled.ok) {
|
|
1875
|
+
const report = asJson
|
|
1876
|
+
? JSON.stringify(compiled, null, 2)
|
|
1877
|
+
: [
|
|
1878
|
+
`# BlendOps Plan Compilation Failed (Invalid SceneSpec)`,
|
|
1879
|
+
...compiled.validation.errors.map((e) => ` - ${e}`),
|
|
1880
|
+
`Runtime status: Not Run`,
|
|
1881
|
+
`Artifact status: Not Produced`,
|
|
1882
|
+
].join('\n');
|
|
1883
|
+
return {
|
|
1884
|
+
ok: false,
|
|
1885
|
+
exitCode: 1,
|
|
1886
|
+
report,
|
|
1887
|
+
data: compiled,
|
|
1888
|
+
runtimeStatus: 'Not Run',
|
|
1889
|
+
artifactStatus: 'Not Produced',
|
|
1890
|
+
};
|
|
1891
|
+
}
|
|
1892
|
+
|
|
1893
|
+
if (outPath) {
|
|
1894
|
+
writeFileAtomicallySafe(outPath, JSON.stringify(compiled.plan, null, 2) + '\n', {
|
|
1895
|
+
repoRoot,
|
|
1896
|
+
projectDir,
|
|
1897
|
+
});
|
|
1898
|
+
}
|
|
1899
|
+
|
|
1900
|
+
const inspection = inspectExecutionPlan(compiled.plan, { repoRoot, projectDir });
|
|
1901
|
+
const report = asJson
|
|
1902
|
+
? JSON.stringify(compiled.plan, null, 2)
|
|
1903
|
+
: formatPlanInspectionHumanReport(inspection);
|
|
1904
|
+
|
|
1905
|
+
const isBlocked = compiled.plan.status === 'blocked';
|
|
1906
|
+
return {
|
|
1907
|
+
ok: !isBlocked,
|
|
1908
|
+
exitCode: isBlocked ? 2 : 0,
|
|
1909
|
+
report,
|
|
1910
|
+
data: compiled.plan,
|
|
1911
|
+
runtimeStatus: 'Not Run',
|
|
1912
|
+
artifactStatus: 'Not Produced',
|
|
1913
|
+
};
|
|
1914
|
+
}
|
|
1915
|
+
|
|
1916
|
+
if (sub === 'plan-inspect') {
|
|
1917
|
+
const inspection = inspectExecutionPlan(targetPath, { repoRoot, projectDir });
|
|
1918
|
+
const report = asJson
|
|
1919
|
+
? JSON.stringify(inspection, null, 2)
|
|
1920
|
+
: formatPlanInspectionHumanReport(inspection);
|
|
1921
|
+
return {
|
|
1922
|
+
ok: inspection.valid,
|
|
1923
|
+
exitCode: inspection.valid ? 0 : 1,
|
|
1924
|
+
report,
|
|
1925
|
+
data: inspection,
|
|
1926
|
+
runtimeStatus: 'Not Run',
|
|
1927
|
+
artifactStatus: 'Not Produced',
|
|
1928
|
+
};
|
|
1929
|
+
}
|
|
1930
|
+
|
|
1931
|
+
return {
|
|
1932
|
+
ok: false,
|
|
1933
|
+
exitCode: 1,
|
|
1934
|
+
report: `Unknown plan subcommand: ${sub}`,
|
|
1935
|
+
runtimeStatus: 'Not Run',
|
|
1936
|
+
artifactStatus: 'Not Produced',
|
|
1937
|
+
};
|
|
1938
|
+
}
|
|
1939
|
+
|
|
1940
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
|
|
1941
|
+
const args = process.argv.slice(2);
|
|
1942
|
+
const res = runPlanCliSubcommand(args, { repoRoot: DEFAULT_REPO_ROOT });
|
|
1943
|
+
console.log(res.report);
|
|
1944
|
+
process.exit(res.exitCode);
|
|
1945
|
+
}
|