blendops 0.0.0-stage → 1.0.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 +62 -0
- package/LICENSE +21 -0
- package/README.md +189 -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 +72 -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/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 +99 -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 +5369 -0
- package/scripts/runtime-orchestrator.mjs +7652 -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,2376 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import fs from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { fileURLToPath } from 'node:url';
|
|
5
|
+
import Ajv2020 from 'ajv/dist/2020.js';
|
|
6
|
+
import { validateEvidencePacket } from './validate-evidence-packet.mjs';
|
|
7
|
+
|
|
8
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
9
|
+
const DEFAULT_ROOT = path.resolve(__dirname, '..');
|
|
10
|
+
|
|
11
|
+
const STOP_WORDS = new Set([
|
|
12
|
+
'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from',
|
|
13
|
+
'how', 'in', 'into', 'is', 'it', 'of', 'on', 'or', 'that', 'the',
|
|
14
|
+
'their', 'this', 'to', 'use', 'using', 'vs', 'when', 'with',
|
|
15
|
+
'la', 'va', 'cua', 'cho', 'trong', 'voi', 'khi', 'nhu', 'the', 'nao',
|
|
16
|
+
'mot', 'cac', 'nhung', 'duoc', 'can', 'lam', 'sao', 'de'
|
|
17
|
+
]);
|
|
18
|
+
|
|
19
|
+
const OUT_OF_SCOPE_TOKENS = new Set([
|
|
20
|
+
'houdini', 'vex', 'wrangle', 'pyro', 'solaris', 'karma', 'lops',
|
|
21
|
+
'unreal', 'nanite', 'lumen', 'niagara', 'metasounds', 'blueprint',
|
|
22
|
+
'maya', 'xgen', 'bifrost', 'arnold', 'hypershade', 'aistandardsurface',
|
|
23
|
+
'3dsmax', 'tyflow', 'vray', 'vraymtl', 'railclone',
|
|
24
|
+
'cinema4d', 'c4d', 'mograph', 'xpresso',
|
|
25
|
+
'redshift', 'zbrush', 'zsphere', 'zremesher', 'dynamesh', 'subtoolfibermesh',
|
|
26
|
+
'substancepainter', 'sbsar',
|
|
27
|
+
'unity', 'urp', 'hdrp', 'shadergraph', 'assetbundles', 'monobehaviour',
|
|
28
|
+
'autocad', 'revit', 'sketchup', 'katana', 'nuke', 'houdinifx',
|
|
29
|
+
'postgresql', 'btree', 'kubernetes', 'helm', 'dockerfile', 'terraform', 'nextjs', 'redux'
|
|
30
|
+
]);
|
|
31
|
+
|
|
32
|
+
const OUT_OF_SCOPE_PHRASES = [
|
|
33
|
+
'cinema 4d',
|
|
34
|
+
'3ds max',
|
|
35
|
+
'unreal engine',
|
|
36
|
+
'unity engine',
|
|
37
|
+
'substance painter',
|
|
38
|
+
'autodesk maya',
|
|
39
|
+
'maya xgen',
|
|
40
|
+
'arnold render',
|
|
41
|
+
'redshift render',
|
|
42
|
+
'houdini vex',
|
|
43
|
+
'houdini pyro',
|
|
44
|
+
'zbrush zremesher'
|
|
45
|
+
];
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Deterministic bilingual (Vietnamese -> English) 3D/Blender terminology expansion map.
|
|
49
|
+
* Keys are Vietnamese folded (ASCII lowercase) phrases/tokens; values are canonical English tokens.
|
|
50
|
+
*/
|
|
51
|
+
export const VIETNAMESE_DOMAIN_SYNONYMS = Object.freeze({
|
|
52
|
+
// Modeling & topology
|
|
53
|
+
'luoi tu giac': ['quad', 'dominant', 'subdivision', 'topology', 'edge', 'loops'],
|
|
54
|
+
'tu giac': ['quad', 'topology', 'subdivision'],
|
|
55
|
+
'chia luoi be mat': ['subdivision', 'surface', 'catmull', 'clark', 'topology'],
|
|
56
|
+
'cuc 5 canh': ['pole', 'poles', 'valence', 'subdivision', 'pinching'],
|
|
57
|
+
'nhon be mat': ['pinching', 'subdivision', 'poles', 'holding', 'loops'],
|
|
58
|
+
'phap tuyen bi nguoc': ['inverted', 'face', 'normals', 'recalculate', 'outside', 'manifold'],
|
|
59
|
+
'dao nguoc phap tuyen': ['inverted', 'face', 'normals', 'recalculate', 'outside', 'manifold'],
|
|
60
|
+
'phap tuyen': ['normals', 'face', 'normal', 'weighted'],
|
|
61
|
+
'khong kin': ['non-manifold', 'manifold', 'watertight', 'open', 'edges', 'hygiene'],
|
|
62
|
+
'loi luoi': ['non-manifold', 'manifold', 'normals', 'scale', 'hygiene', 'inspection'],
|
|
63
|
+
'ty le am': ['negative', 'scale', 'unapplied', 'transform', 'apply'],
|
|
64
|
+
'ap dung scale': ['apply', 'scale', 'transform', 'unapplied', 'normals'],
|
|
65
|
+
'ap dung ty le': ['apply', 'scale', 'transform', 'unapplied', 'normals', 'hygiene'],
|
|
66
|
+
'vat cung': ['hard', 'surface', 'prop', 'mechanical', 'bevel', 'boolean'],
|
|
67
|
+
'vat dung co khi': ['hard', 'surface', 'prop', 'mechanical', 'bevel', 'boolean'],
|
|
68
|
+
'mechanical': ['hard', 'surface', 'prop', 'mechanical', 'bevel', 'boolean'],
|
|
69
|
+
'vat mep': ['bevel', 'segments', 'modifier', 'hard', 'surface', 'crease'],
|
|
70
|
+
'vat canh': ['bevel', 'segments', 'modifier', 'hard', 'surface', 'shading', 'cleanup'],
|
|
71
|
+
'cat khoi boolean': ['boolean', 'bevel', 'shading', 'cleanup', 'weighted', 'normal'],
|
|
72
|
+
'cat boolean': ['boolean', 'bevel', 'shading', 'cleanup', 'weighted', 'normal'],
|
|
73
|
+
'dieu khac': ['sculpt', 'retopology', 'voxel', 'remesh', 'multires', 'shrinkwrap', 'organic'],
|
|
74
|
+
'diu khac': ['sculpt', 'retopology', 'voxel', 'remesh', 'multires', 'organic'],
|
|
75
|
+
'retopo': ['retopology', 'sculpt', 'quad', 'shrinkwrap', 'organic'],
|
|
76
|
+
'khe ranh': ['panel', 'gap', 'creases', 'cad', 'hard', 'surface', 'detailing'],
|
|
77
|
+
|
|
78
|
+
// Geometry Nodes & procedural
|
|
79
|
+
'rai vat the': ['scatter', 'distribute', 'points', 'faces', 'poisson', 'disk', 'instances', 'geometry', 'nodes'],
|
|
80
|
+
'rai phan bo': ['scatter', 'distribute', 'points', 'faces', 'poisson', 'disk', 'slope', 'masking', 'geometry', 'nodes'],
|
|
81
|
+
'rai cay co': ['scatter', 'poisson', 'disk', 'slope', 'masking', 'foliage', 'geometry', 'nodes'],
|
|
82
|
+
'rai da': ['scatter', 'poisson', 'disk', 'slope', 'geometry', 'nodes', 'instance'],
|
|
83
|
+
'do doc': ['slope', 'mask', 'masking', 'normal', 'dot', 'product', 'scatter', 'poisson', 'disk'],
|
|
84
|
+
'hien thuc hoa instance': ['realize', 'instances', 'geometry', 'nodes', 'memory', 'export', 'instancing'],
|
|
85
|
+
'nut hinh hoc': ['geometry', 'nodes', 'fields', 'procedural', 'scatter', 'instances'],
|
|
86
|
+
'thuoc tinh': ['attribute', 'anonymous', 'named', 'capture', 'store', 'fields', 'geometry', 'nodes'],
|
|
87
|
+
'tham so hoa': ['parametric', 'procedural', 'geometry', 'nodes', 'generator'],
|
|
88
|
+
|
|
89
|
+
// UV, texturing & baking
|
|
90
|
+
'trai uv': ['uv', 'unwrap', 'seam', 'placement', 'texel', 'density', 'margin', 'island'],
|
|
91
|
+
'duong cat uv': ['uv', 'seam', 'placement', 'unwrap', 'texel', 'density'],
|
|
92
|
+
'duong cat seam': ['uv', 'seam', 'placement', 'unwrap', 'texel', 'density'],
|
|
93
|
+
'mat do diem anh': ['texel', 'density', 'pixels', 'meter', 'uv', 'seam'],
|
|
94
|
+
'mat do texel': ['texel', 'density', 'pixels', 'meter', 'uv', 'seam', 'placement'],
|
|
95
|
+
'nuong normal map': ['bake', 'baking', 'normal', 'map', 'tangent', 'space', 'cage', 'extrusion', 'high', 'low', 'poly', 'mikktspace'],
|
|
96
|
+
'ban do phap tuyen': ['normal', 'map', 'baking', 'high', 'low', 'poly', 'cage', 'tangent', 'mikktspace'],
|
|
97
|
+
'nuong texture': ['bake', 'baking', 'normal', 'ao', 'ambient', 'occlusion', 'cage'],
|
|
98
|
+
'nhieu o udim': ['udim', 'multi', 'tile', '1001', '1002', 'single', 'atlas', 'uv', 'packing', 'gltf'],
|
|
99
|
+
|
|
100
|
+
// Materials, shaders & PBR
|
|
101
|
+
'vat lieu pbr': ['principled', 'bsdf', 'v2', 'energy', 'conserving', 'pbr', 'metallic', 'roughness', 'albedo'],
|
|
102
|
+
'vat lieu kim loai': ['metallic', 'principled', 'bsdf', 'pbr', 'ibl', 'environment', 'threejs', 'black', 'tone', 'mapping'],
|
|
103
|
+
'bi den trong threejs': ['metallic', 'black', 'threejs', 'r3f', 'tone', 'mapping', 'environment', 'ibl', 'shader', 'export', 'parity'],
|
|
104
|
+
'dong goi kenh orm': ['orm', 'occlusion', 'roughness', 'metallic', 'channel', 'packing', 'non-color', 'linear', 'srgb'],
|
|
105
|
+
'do nham': ['roughness', 'orm', 'channel', 'packing', 'non-color', 'principled', 'bsdf'],
|
|
106
|
+
'khong tuong thich gltf': ['shader', 'node', 'gltf', 'export', 'portability', 'procedural', 'bake'],
|
|
107
|
+
|
|
108
|
+
// Lighting, camera & rendering
|
|
109
|
+
'anh sang ba diem': ['three', 'point', 'lighting', 'key', 'fill', 'rim', 'ratio', 'hdri', 'studio'],
|
|
110
|
+
'anh sang 3 diem': ['three', 'point', 'lighting', 'key', 'fill', 'rim', 'ratio', 'hdri', 'studio'],
|
|
111
|
+
'den chinh': ['key', 'fill', 'rim', 'three', 'point', 'studio', 'lighting'],
|
|
112
|
+
'anh sang studio': ['studio', 'three', 'point', 'lighting', 'key', 'fill', 'rim', 'hdri', 'product', 'hero'],
|
|
113
|
+
'ong kinh may anh': ['camera', 'focal', 'length', '85mm', 'sensor', 'width', 'f-stop', 'depth', 'field', 'dof'],
|
|
114
|
+
'tieu cu': ['camera', 'focal', 'length', '85mm', 'sensor', 'f-stop', 'dof', 'physically', 'based'],
|
|
115
|
+
'khau do': ['f-stop', 'dof', 'depth', 'field', 'camera', 'lens'],
|
|
116
|
+
'xoa phong': ['dof', 'depth', 'field', 'f-stop', 'camera', 'lens'],
|
|
117
|
+
'do sau truong anh': ['depth', 'field', 'dof', 'f-stop', 'camera', 'focal', 'length'],
|
|
118
|
+
'quan ly mau agx': ['agx', 'filmic', 'color', 'management', 'view', 'transform', 'cycles', 'eevee'],
|
|
119
|
+
'chay sang highlight': ['agx', 'filmic', 'highlight', 'desaturation', 'color', 'management', 'cycles', 'eevee'],
|
|
120
|
+
'khu nhieu': ['denoising', 'denoise', 'openimagedenoise', 'adaptive', 'sampling', 'cycles', 'eevee', 'agx'],
|
|
121
|
+
'so sanh cycles va eevee': ['cycles', 'eevee', 'render', 'engine', 'agx', 'filmic', 'path', 'tracing'],
|
|
122
|
+
'san pham hero': ['product', 'hero', 'scene', 'studio', 'lighting', 'render', 'glb'],
|
|
123
|
+
'giay sneaker': ['sneaker', 'product', 'hero', 'scene', 'cyberpunk', 'studio'],
|
|
124
|
+
|
|
125
|
+
// Rigging & animation
|
|
126
|
+
'gan xuong': ['armature', 'rigging', 'rigged', 'skinning', 'joint', 'weights', 'vertex', 'bone', 'roll', 'hierarchy'],
|
|
127
|
+
'trong so xuong': ['joint', 'weights', 'vertex', 'skinning', 'armature', 'normalize'],
|
|
128
|
+
'toi da 4 xuong': ['armature', 'skinning', 'max', '4', 'joint', 'weights', 'vertex', 'normalize'],
|
|
129
|
+
'hanh dong nla': ['nla', 'action', 'baking', 'visual', 'keying', 'keyframes', 'morph', 'targets', 'shape', 'keys', 'animation'],
|
|
130
|
+
'nuong hoat anh': ['nla', 'action', 'baking', 'keyframes', 'morph', 'target', 'export'],
|
|
131
|
+
'chuyen dong nhan vat': ['rigged', 'animated', 'character', 'armature', 'skinning', 'nla', 'action', 'baking'],
|
|
132
|
+
'chan dung nhan vat': ['character', 'portrait', 'camera', 'lighting', 'rigged'],
|
|
133
|
+
|
|
134
|
+
// Simulation & VFX
|
|
135
|
+
'mo phong vat ly': ['rigid', 'body', 'cloth', 'physics', 'simulation', 'cache', 'baking', 'substeps', 'collision'],
|
|
136
|
+
'va cham vat cung': ['rigid', 'body', 'collision', 'substeps', 'convex', 'hull', 'physics', 'bake'],
|
|
137
|
+
'mo phong vai': ['cloth', 'simulation', 'collision', 'cache', 'baking', 'physics'],
|
|
138
|
+
'suong mu the tich': ['volumetrics', 'volumetric', 'fog', 'principled', 'volume', 'tradeoffs', 'eevee', 'cycles'],
|
|
139
|
+
|
|
140
|
+
// Environment & architecture
|
|
141
|
+
'boi canh moi truong': ['stylized', 'environment', 'scene', 'diorama', 'architectural', 'blockout', 'scatter', 'foliage', 'fog'],
|
|
142
|
+
'kien truc noi that': ['modular', 'architectural', 'grid', 'snapping', 'metric', 'scale', 'interior', 'doorway'],
|
|
143
|
+
'cua so': ['interior', 'architectural', 'modular', 'grid', 'environment', 'lighting'],
|
|
144
|
+
'luoi kien truc': ['modular', 'architectural', 'grid', 'snapping', 'corner', 'pivot', 'metric', 'scale'],
|
|
145
|
+
'phan lop tien canh': ['foreground', 'midground', 'background', 'depth', 'layering', 'environment', 'atmospheric', 'perspective'],
|
|
146
|
+
|
|
147
|
+
// Optimization, LOD & glTF/Web
|
|
148
|
+
'ngan sach da giac': ['triangle', 'count', 'budget', 'draw', 'calls', 'vram', 'mobile', 'web', 'desktop'],
|
|
149
|
+
'dien thoai di dong': ['mobile', 'web', 'ready', 'asset', 'optimization', 'triangle', 'budget', 'ktx2', 'draco'],
|
|
150
|
+
'giam da giac': ['decimate', 'decimation', 'lod', 'hierarchy', 'triangle', 'budget', 'optimization'],
|
|
151
|
+
'toi uu hoa web mobile': ['web', 'ready', 'mobile', 'asset', 'optimization', 'decimate', 'lod', 'draco', 'meshopt', 'ktx2', 'compression'],
|
|
152
|
+
'nen draco va ktx2': ['draco', 'meshopt', 'ktx2', 'basis', 'universal', 'texture', 'vram', 'geometry', 'compression'],
|
|
153
|
+
'muc do chi tiet lod': ['lod', 'level', 'detail', 'decimate', 'decimation', 'hierarchy', 'strategy', 'silhouette'],
|
|
154
|
+
'he toa do gltf': ['gltf', 'coordinate', 'system', 'right', 'handed', '+y', 'up', '+z', 'forward', 'trs', 'transform'],
|
|
155
|
+
'xuat file glb': ['blender', 'glb', 'export', 'handoff', 'khronos', 'gltf', 'validator', 'react', 'three', 'fiber', 'binary', 'chunk'],
|
|
156
|
+
'ban giao file glb': ['blender', 'glb', 'handoff', 'khronos', 'validation', 'coordinate', 'system', 'react', 'three', 'fiber'],
|
|
157
|
+
'kiem tra chat luong': ['scene', 'quality', 'inspection', 'correction', 'audit', 'non-manifold', 'normals', 'scale']
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
export const REQUIRED_DOMAINS = [
|
|
161
|
+
'modeling-and-topology',
|
|
162
|
+
'hard-surface-and-organic',
|
|
163
|
+
'geometry-nodes-and-procedural',
|
|
164
|
+
'uv-texturing-and-baking',
|
|
165
|
+
'materials-shaders-and-pbr',
|
|
166
|
+
'lighting-camera-and-rendering',
|
|
167
|
+
'rigging-and-animation',
|
|
168
|
+
'simulation-and-vfx',
|
|
169
|
+
'environment-and-architecture',
|
|
170
|
+
'optimization-lod-and-performance',
|
|
171
|
+
'interchange-gltf-and-web'
|
|
172
|
+
];
|
|
173
|
+
|
|
174
|
+
export const REQUIRED_RECIPE_IDS = [
|
|
175
|
+
'recipe.product-hero-scene',
|
|
176
|
+
'recipe.stylized-environment-scene',
|
|
177
|
+
'recipe.hard-surface-prop',
|
|
178
|
+
'recipe.procedural-geometry-nodes-asset',
|
|
179
|
+
'recipe.uv-and-pbr-material-preparation',
|
|
180
|
+
'recipe.presentation-lighting-and-camera',
|
|
181
|
+
'recipe.rigged-and-animated-asset',
|
|
182
|
+
'recipe.scene-quality-inspection-and-correction',
|
|
183
|
+
'recipe.blender-to-glb-handoff',
|
|
184
|
+
'recipe.web-ready-asset-optimization'
|
|
185
|
+
];
|
|
186
|
+
|
|
187
|
+
function readJson(filePath) {
|
|
188
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
function writeJsonStable(filePath, data) {
|
|
192
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
|
193
|
+
fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Resolves catalog file paths across either the canonical BlendOps repository/package root
|
|
198
|
+
* (`registry/*`, `schemas/*`) or a project-local installed catalog root (`.blendops/catalog/*`).
|
|
199
|
+
*/
|
|
200
|
+
export function resolveCatalogPaths(rootDir = DEFAULT_ROOT) {
|
|
201
|
+
const absRoot = path.resolve(rootDir);
|
|
202
|
+
const directCatalogCandidate = path.join(absRoot, 'knowledge-catalog.json');
|
|
203
|
+
const installedCatalogCandidate = path.join(absRoot, '.blendops', 'catalog', 'knowledge-catalog.json');
|
|
204
|
+
|
|
205
|
+
if (fs.existsSync(directCatalogCandidate)) {
|
|
206
|
+
return {
|
|
207
|
+
mode: 'installed-catalog-dir',
|
|
208
|
+
baseDir: absRoot,
|
|
209
|
+
sourcesPath: path.join(absRoot, 'knowledge-sources.json'),
|
|
210
|
+
knowledgePath: path.join(absRoot, 'knowledge-catalog.json'),
|
|
211
|
+
recipesPath: path.join(absRoot, 'recipe-catalog.json'),
|
|
212
|
+
indexPath: path.join(absRoot, 'catalog-index.json'),
|
|
213
|
+
skillsPath: fs.existsSync(path.join(absRoot, 'skills-summary.json'))
|
|
214
|
+
? path.join(absRoot, 'skills-summary.json')
|
|
215
|
+
: path.join(absRoot, 'registry/skills.json'),
|
|
216
|
+
sourcesSchemaPath: path.join(absRoot, 'schemas/knowledge-source-registry.schema.json'),
|
|
217
|
+
knowledgeSchemaPath: path.join(absRoot, 'schemas/knowledge-record.schema.json'),
|
|
218
|
+
recipeSchemaPath: path.join(absRoot, 'schemas/recipe-record.schema.json')
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
if (
|
|
223
|
+
!fs.existsSync(path.join(absRoot, 'registry/knowledge-catalog.json')) &&
|
|
224
|
+
fs.existsSync(installedCatalogCandidate)
|
|
225
|
+
) {
|
|
226
|
+
const catDir = path.join(absRoot, '.blendops', 'catalog');
|
|
227
|
+
return {
|
|
228
|
+
mode: 'project-local-blendops-catalog',
|
|
229
|
+
baseDir: catDir,
|
|
230
|
+
sourcesPath: path.join(catDir, 'knowledge-sources.json'),
|
|
231
|
+
knowledgePath: path.join(catDir, 'knowledge-catalog.json'),
|
|
232
|
+
recipesPath: path.join(catDir, 'recipe-catalog.json'),
|
|
233
|
+
indexPath: path.join(catDir, 'catalog-index.json'),
|
|
234
|
+
skillsPath: path.join(catDir, 'skills-summary.json'),
|
|
235
|
+
sourcesSchemaPath: path.join(catDir, 'schemas/knowledge-source-registry.schema.json'),
|
|
236
|
+
knowledgeSchemaPath: path.join(catDir, 'schemas/knowledge-record.schema.json'),
|
|
237
|
+
recipeSchemaPath: path.join(catDir, 'schemas/recipe-record.schema.json')
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
return {
|
|
242
|
+
mode: 'canonical-repo',
|
|
243
|
+
baseDir: absRoot,
|
|
244
|
+
sourcesPath: path.join(absRoot, 'registry/knowledge-sources.json'),
|
|
245
|
+
knowledgePath: path.join(absRoot, 'registry/knowledge-catalog.json'),
|
|
246
|
+
recipesPath: path.join(absRoot, 'registry/recipe-catalog.json'),
|
|
247
|
+
indexPath: path.join(absRoot, 'registry/catalog-index.json'),
|
|
248
|
+
skillsPath: path.join(absRoot, 'registry/skills.json'),
|
|
249
|
+
sourcesSchemaPath: path.join(absRoot, 'schemas/knowledge-source-registry.schema.json'),
|
|
250
|
+
knowledgeSchemaPath: path.join(absRoot, 'schemas/knowledge-record.schema.json'),
|
|
251
|
+
recipeSchemaPath: path.join(absRoot, 'schemas/recipe-record.schema.json')
|
|
252
|
+
};
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Folds Vietnamese diacritics and Unicode combining marks to ASCII lowercase while
|
|
257
|
+
* preserving technical symbols (+, #, ., -).
|
|
258
|
+
*/
|
|
259
|
+
export function foldVietnameseDiacritics(input) {
|
|
260
|
+
if (!input) return '';
|
|
261
|
+
return String(input)
|
|
262
|
+
.normalize('NFC')
|
|
263
|
+
.replace(/[đĐ]/g, 'd')
|
|
264
|
+
.normalize('NFD')
|
|
265
|
+
.replace(/[\u0300-\u036f]/g, '')
|
|
266
|
+
.toLowerCase();
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* Detects whether a query contains Vietnamese characters or known Vietnamese 3D phrases.
|
|
271
|
+
*/
|
|
272
|
+
export function detectQueryLanguage(query) {
|
|
273
|
+
if (!query) return 'en';
|
|
274
|
+
const raw = String(query).normalize('NFC');
|
|
275
|
+
const hasVietnameseChars = /[ăâđêôơưáàảãạấầẩẫậắằẳẵặéèẻẽẹếềểễệíìỉĩịóòỏõọốồổỗộớờởỡợúùủũụứừửữựýỳỷỹỵ]/i.test(raw);
|
|
276
|
+
const folded = foldVietnameseDiacritics(raw);
|
|
277
|
+
const hasViPhrase = Object.keys(VIETNAMESE_DOMAIN_SYNONYMS).some((phrase) => folded.includes(phrase));
|
|
278
|
+
if (!hasVietnameseChars && !hasViPhrase) {
|
|
279
|
+
return 'en';
|
|
280
|
+
}
|
|
281
|
+
const hasEnglishTechTerms = /\b(blender|gltf|glb|cycles|eevee|agx|filmic|uv|pbr|udim|draco|meshopt|ktx2|threejs|r3f|geometry nodes|principled bsdf|nla|mikktspace)\b/i.test(raw);
|
|
282
|
+
return hasEnglishTechTerms ? 'mixed_vi_en' : 'vi';
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
export function tokenize(text) {
|
|
286
|
+
if (!text) return [];
|
|
287
|
+
const nfc = String(text).normalize('NFC');
|
|
288
|
+
const folded = foldVietnameseDiacritics(nfc);
|
|
289
|
+
|
|
290
|
+
const baseTokens = folded
|
|
291
|
+
.replace(/[^a-z0-9+#.-]+/g, ' ')
|
|
292
|
+
.split(/\s+/)
|
|
293
|
+
.map((t) => t.replace(/^[.-]+|[.-]+$/g, ''))
|
|
294
|
+
.filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
|
|
295
|
+
|
|
296
|
+
// Expand Vietnamese domain phrases deterministically
|
|
297
|
+
const expanded = [...baseTokens];
|
|
298
|
+
const cleanSpaceFolded = folded.replace(/[^a-z0-9+#.-]+/g, ' ').trim();
|
|
299
|
+
for (const [viPhrase, enTokens] of Object.entries(VIETNAMESE_DOMAIN_SYNONYMS)) {
|
|
300
|
+
if (cleanSpaceFolded.includes(viPhrase)) {
|
|
301
|
+
for (const tok of enTokens) {
|
|
302
|
+
if (!STOP_WORDS.has(tok)) {
|
|
303
|
+
expanded.push(tok);
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
return Array.from(new Set(expanded));
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
export const normalizeAndTokenizeBilingual = tokenize;
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* Deterministic workflow stage derivation rule from canonical `registry/skills.json`
|
|
316
|
+
* (`category`, `role`, `id`). Explicitly labeled as derived in audit outputs.
|
|
317
|
+
*/
|
|
318
|
+
export const WORKFLOW_STAGE_DERIVATION_RULE =
|
|
319
|
+
'Derived deterministically from registry/skills.json category + role + skill ID: routing-and-governance/brief-and-scope/recipe-and-pack-governance -> discover-and-plan; asset-and-library-governance -> source-and-clear-assets; runtime-and-bridge-governance -> runtime-preflight; scene-and-domain-planning/color-and-render-decisions -> stage-camera-lighting-and-lookdev; quality-and-budget-validation -> inspect-and-validate; web-and-glb-handoff/evidence-and-reporting -> verify-evidence-and-handoff.';
|
|
320
|
+
|
|
321
|
+
export function deriveSkillWorkflowStage(skill) {
|
|
322
|
+
const cat = skill.category || '';
|
|
323
|
+
const id = skill.id || '';
|
|
324
|
+
if (
|
|
325
|
+
cat === 'routing-and-governance' ||
|
|
326
|
+
cat === 'brief-and-scope' ||
|
|
327
|
+
cat === 'recipe-and-pack-governance' ||
|
|
328
|
+
id === 'blender-brainstorming'
|
|
329
|
+
) {
|
|
330
|
+
return 'discover-and-plan';
|
|
331
|
+
}
|
|
332
|
+
if (cat === 'asset-and-library-governance') {
|
|
333
|
+
return 'source-and-clear-assets';
|
|
334
|
+
}
|
|
335
|
+
if (cat === 'runtime-and-bridge-governance') {
|
|
336
|
+
return 'runtime-preflight';
|
|
337
|
+
}
|
|
338
|
+
if (cat === 'scene-and-domain-planning' || cat === 'color-and-render-decisions') {
|
|
339
|
+
return 'stage-camera-lighting-and-lookdev';
|
|
340
|
+
}
|
|
341
|
+
if (cat === 'quality-and-budget-validation' || id === 'blender-troubleshooting') {
|
|
342
|
+
return 'inspect-and-validate';
|
|
343
|
+
}
|
|
344
|
+
if (cat === 'web-and-glb-handoff' || cat === 'evidence-and-reporting') {
|
|
345
|
+
return 'verify-evidence-and-handoff';
|
|
346
|
+
}
|
|
347
|
+
return 'stage-camera-lighting-and-lookdev';
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
function classifySkillRole(skill) {
|
|
351
|
+
const cat = skill.category || '';
|
|
352
|
+
const id = skill.id || '';
|
|
353
|
+
if (
|
|
354
|
+
cat === 'routing-and-governance' ||
|
|
355
|
+
cat === 'brief-and-scope' ||
|
|
356
|
+
cat === 'recipe-and-pack-governance'
|
|
357
|
+
) {
|
|
358
|
+
return 'intake-routing-or-governance';
|
|
359
|
+
}
|
|
360
|
+
if (cat === 'asset-and-library-governance') {
|
|
361
|
+
return 'asset-sourcing-license-or-style-governance';
|
|
362
|
+
}
|
|
363
|
+
if (cat === 'runtime-and-bridge-governance') {
|
|
364
|
+
return 'runtime-bridge-or-preflight-governance';
|
|
365
|
+
}
|
|
366
|
+
if (cat === 'quality-and-budget-validation') {
|
|
367
|
+
if (id.includes('budget') || id.includes('polycount')) {
|
|
368
|
+
return 'optimization-or-budget-audit';
|
|
369
|
+
}
|
|
370
|
+
return 'scene-inspection-or-quality-validation';
|
|
371
|
+
}
|
|
372
|
+
if (cat === 'scene-and-domain-planning' || cat === 'color-and-render-decisions') {
|
|
373
|
+
if (id.includes('material') || id.includes('color')) {
|
|
374
|
+
return 'uv-material-or-lookdev-workflow';
|
|
375
|
+
}
|
|
376
|
+
return 'lighting-camera-or-scene-planning-workflow';
|
|
377
|
+
}
|
|
378
|
+
if (cat === 'web-and-glb-handoff') {
|
|
379
|
+
return 'export-interchange-or-handoff';
|
|
380
|
+
}
|
|
381
|
+
if (cat === 'evidence-and-reporting') {
|
|
382
|
+
return 'review-recovery-or-evidence';
|
|
383
|
+
}
|
|
384
|
+
return 'modeling-or-procedural-workflow';
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
function readSkillMarkdownMetadata(rootDir, skillId) {
|
|
388
|
+
const mdPath = path.join(rootDir, 'skills', skillId, 'SKILL.md');
|
|
389
|
+
if (!fs.existsSync(mdPath)) {
|
|
390
|
+
return {
|
|
391
|
+
display_name: skillId,
|
|
392
|
+
frontmatter_description: '',
|
|
393
|
+
laws_referenced: ['laws/evidence-before-done.md', 'laws/non-blender-user-language.md']
|
|
394
|
+
};
|
|
395
|
+
}
|
|
396
|
+
const raw = fs.readFileSync(mdPath, 'utf8');
|
|
397
|
+
const h1Match = raw.match(/^#\s+(.+?)\s*$/m);
|
|
398
|
+
const descMatch = raw.match(/^description:\s*(.+?)\s*$/m);
|
|
399
|
+
const laws = [];
|
|
400
|
+
for (const lawName of [
|
|
401
|
+
'official-runtime-only',
|
|
402
|
+
'no-arbitrary-python-interface',
|
|
403
|
+
'evidence-before-done',
|
|
404
|
+
'non-blender-user-language'
|
|
405
|
+
]) {
|
|
406
|
+
if (raw.includes(lawName)) {
|
|
407
|
+
laws.push(`laws/${lawName}.md`);
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
return {
|
|
411
|
+
display_name: h1Match ? h1Match[1].trim() : skillId,
|
|
412
|
+
frontmatter_description: descMatch ? descMatch[1].trim().replace(/^['"]|['"]$/g, '') : '',
|
|
413
|
+
laws_referenced: laws.length > 0 ? laws : ['laws/evidence-before-done.md']
|
|
414
|
+
};
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
function inspectReferenceMarkdownFile(rootDir, relPath) {
|
|
418
|
+
const absPath = path.join(rootDir, relPath);
|
|
419
|
+
if (!fs.existsSync(absPath)) {
|
|
420
|
+
return { title: path.basename(relPath), headings: [], lineCount: 0, byteSize: 0 };
|
|
421
|
+
}
|
|
422
|
+
const raw = fs.readFileSync(absPath, 'utf8');
|
|
423
|
+
const lines = raw.split(/\r?\n/);
|
|
424
|
+
const h1 = lines.find((l) => l.startsWith('# '))?.replace(/^#\s+/, '').trim() || path.basename(relPath);
|
|
425
|
+
const headings = lines
|
|
426
|
+
.filter((l) => /^##\s+/.test(l))
|
|
427
|
+
.map((l) => l.replace(/^##\s+/, '').trim());
|
|
428
|
+
return {
|
|
429
|
+
title: h1,
|
|
430
|
+
headings,
|
|
431
|
+
lineCount: lines.length,
|
|
432
|
+
byteSize: Buffer.byteLength(raw, 'utf8')
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
// Cross-skill reference files that touch domain concepts shared across multiple skills and are flagged
|
|
437
|
+
// for periodic human semantic review rather than claiming 100% automated semantic deduplication.
|
|
438
|
+
const SEMANTIC_REVIEW_CANDIDATE_REFS = new Set([
|
|
439
|
+
'skills/product-hero-scene-planner/references/scene-plan-schema.md',
|
|
440
|
+
'skills/r3f-component-plan/references/suspense-placement-rules.md',
|
|
441
|
+
'skills/r3f-component-plan/references/usegltf-caching-rules.md',
|
|
442
|
+
'skills/render-export-evidence/references/evidence-record-templates.md',
|
|
443
|
+
'skills/render-export-evidence/references/truth-label-decision-tree.md',
|
|
444
|
+
'skills/resolution-aspect-decision/references/aspect-defaults.md',
|
|
445
|
+
'skills/resolution-aspect-decision/references/print-vs-screen-rules.md',
|
|
446
|
+
'skills/scene-readiness/references/quality-rubric.md'
|
|
447
|
+
]);
|
|
448
|
+
|
|
449
|
+
/**
|
|
450
|
+
* Validates that any record or classification entry claiming human semantic review
|
|
451
|
+
* includes traceable evidence (reviewer identity, ISO-8601 review timestamp,
|
|
452
|
+
* reviewed scope, and review outcome).
|
|
453
|
+
*/
|
|
454
|
+
export function validateHumanReviewProvenance(entry) {
|
|
455
|
+
const errors = [];
|
|
456
|
+
if (!entry || typeof entry !== 'object') {
|
|
457
|
+
return { valid: false, errors: ['Expected classification or audit record object.'] };
|
|
458
|
+
}
|
|
459
|
+
const claimsHumanReview =
|
|
460
|
+
entry.classification_method === 'human_semantic_review' ||
|
|
461
|
+
entry.review_status === 'human_reviewed';
|
|
462
|
+
if (!claimsHumanReview) {
|
|
463
|
+
return { valid: true, errors: [] };
|
|
464
|
+
}
|
|
465
|
+
const ev = entry.human_review_evidence;
|
|
466
|
+
if (!ev || typeof ev !== 'object') {
|
|
467
|
+
errors.push(
|
|
468
|
+
`Entry "${entry.path || entry.id || 'unknown'}" claims human_semantic_review without a human_review_evidence object.`,
|
|
469
|
+
);
|
|
470
|
+
return { valid: false, errors };
|
|
471
|
+
}
|
|
472
|
+
if (typeof ev.reviewer !== 'string' || ev.reviewer.trim().length < 2) {
|
|
473
|
+
errors.push('human_review_evidence.reviewer must be a non-empty reviewer identity string.');
|
|
474
|
+
}
|
|
475
|
+
if (
|
|
476
|
+
typeof ev.reviewed_at !== 'string' ||
|
|
477
|
+
!/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/.test(ev.reviewed_at)
|
|
478
|
+
) {
|
|
479
|
+
errors.push('human_review_evidence.reviewed_at must be an ISO-8601 date or timestamp.');
|
|
480
|
+
}
|
|
481
|
+
if (typeof ev.reviewed_scope !== 'string' || ev.reviewed_scope.trim().length < 3) {
|
|
482
|
+
errors.push('human_review_evidence.reviewed_scope must be a non-empty string.');
|
|
483
|
+
}
|
|
484
|
+
if (typeof ev.review_outcome !== 'string' || ev.review_outcome.trim().length < 3) {
|
|
485
|
+
errors.push('human_review_evidence.review_outcome must be a non-empty string.');
|
|
486
|
+
}
|
|
487
|
+
return { valid: errors.length === 0, errors };
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
function classifyReferenceFile(rootDir, relPath, promotedMap, humanReviewsMap = new Map()) {
|
|
491
|
+
const promotedTo = promotedMap.get(relPath) || [];
|
|
492
|
+
const fileMeta = inspectReferenceMarkdownFile(rootDir, relPath);
|
|
493
|
+
const humanEvidence = humanReviewsMap.get(relPath) || null;
|
|
494
|
+
if (humanEvidence) {
|
|
495
|
+
const check = validateHumanReviewProvenance({
|
|
496
|
+
path: relPath,
|
|
497
|
+
classification_method: 'human_semantic_review',
|
|
498
|
+
human_review_evidence: humanEvidence,
|
|
499
|
+
});
|
|
500
|
+
if (!check.valid) {
|
|
501
|
+
throw new Error(`Invalid human_review_evidence for ${relPath}: ${check.errors.join('; ')}`);
|
|
502
|
+
}
|
|
503
|
+
}
|
|
504
|
+
|
|
505
|
+
if (
|
|
506
|
+
relPath.startsWith('skills/recipe-fit-assessor/references/') ||
|
|
507
|
+
relPath.startsWith('skills/blender-recipe-decomposer/references/')
|
|
508
|
+
) {
|
|
509
|
+
return {
|
|
510
|
+
path: relPath,
|
|
511
|
+
title: fileMeta.title,
|
|
512
|
+
line_count: fileMeta.lineCount,
|
|
513
|
+
classification: 'recipe_specific_procedure',
|
|
514
|
+
classification_method: humanEvidence
|
|
515
|
+
? 'human_semantic_review'
|
|
516
|
+
: 'rule_based_governance_and_recipe_mapping',
|
|
517
|
+
review_status: humanEvidence
|
|
518
|
+
? 'human_reviewed'
|
|
519
|
+
: 'rule_classified_governance_or_recipe',
|
|
520
|
+
human_review_evidence: humanEvidence,
|
|
521
|
+
rationale:
|
|
522
|
+
'Classified via deterministic skill-path rule and synchronized with registry/recipe-catalog.json for recipe fit scoring and multi-deliverable decomposition.',
|
|
523
|
+
promoted_to_knowledge_ids: promotedTo
|
|
524
|
+
};
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
if (promotedTo.length > 0) {
|
|
528
|
+
return {
|
|
529
|
+
path: relPath,
|
|
530
|
+
title: fileMeta.title,
|
|
531
|
+
line_count: fileMeta.lineCount,
|
|
532
|
+
classification: 'reusable_cross_skill_knowledge',
|
|
533
|
+
classification_method: 'knowledge_promotion_mapping',
|
|
534
|
+
review_status: 'verified_promoted',
|
|
535
|
+
human_review_evidence: humanEvidence,
|
|
536
|
+
rationale: `Domain rules promoted to canonical knowledge record(s): ${promotedTo.join(', ')} while remaining available as a progressive-disclosure skill reference.`,
|
|
537
|
+
promoted_to_knowledge_ids: promotedTo
|
|
538
|
+
};
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
if (
|
|
542
|
+
relPath.startsWith('skills/workflow-stage-router/references/') ||
|
|
543
|
+
relPath.startsWith('skills/pack-prerequisite-checker/references/') ||
|
|
544
|
+
relPath.startsWith('skills/acceptance-criteria-builder/references/') ||
|
|
545
|
+
relPath.startsWith('skills/stage-gates/references/') ||
|
|
546
|
+
relPath.startsWith('skills/done-criteria/references/') ||
|
|
547
|
+
relPath.startsWith('skills/scope-guard/references/') ||
|
|
548
|
+
relPath.startsWith('skills/blendops-help/references/') ||
|
|
549
|
+
relPath.startsWith('skills/runtime-path-picker/references/') ||
|
|
550
|
+
relPath.startsWith('skills/runtime-setup/references/') ||
|
|
551
|
+
relPath.startsWith('skills/runtime-readiness/references/') ||
|
|
552
|
+
relPath.startsWith('skills/bridge-conflicts/references/') ||
|
|
553
|
+
relPath.startsWith('skills/path-one-host-outline/references/') ||
|
|
554
|
+
relPath.startsWith('skills/cli-appendix-job-outline/references/') ||
|
|
555
|
+
relPath.startsWith('skills/runtime-attempt-report/references/')
|
|
556
|
+
) {
|
|
557
|
+
return {
|
|
558
|
+
path: relPath,
|
|
559
|
+
title: fileMeta.title,
|
|
560
|
+
line_count: fileMeta.lineCount,
|
|
561
|
+
classification: 'workflow_or_pack_governance',
|
|
562
|
+
classification_method: humanEvidence
|
|
563
|
+
? 'human_semantic_review'
|
|
564
|
+
: 'rule_based_governance_and_recipe_mapping',
|
|
565
|
+
review_status: humanEvidence
|
|
566
|
+
? 'human_reviewed'
|
|
567
|
+
: 'rule_classified_governance_or_recipe',
|
|
568
|
+
human_review_evidence: humanEvidence,
|
|
569
|
+
rationale:
|
|
570
|
+
'Classified via deterministic governance skill-path rule covering BlendOps workflow stage routing, pack prerequisites, stage gates, stop criteria, or Path 1 / Path 2 / CLI runtime boundaries.',
|
|
571
|
+
promoted_to_knowledge_ids: []
|
|
572
|
+
};
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
const needsReview = SEMANTIC_REVIEW_CANDIDATE_REFS.has(relPath);
|
|
576
|
+
return {
|
|
577
|
+
path: relPath,
|
|
578
|
+
title: fileMeta.title,
|
|
579
|
+
line_count: fileMeta.lineCount,
|
|
580
|
+
classification: 'skill_specific_operating_instructions',
|
|
581
|
+
classification_method: 'rule_based_path_and_heading_inspection',
|
|
582
|
+
review_status: needsReview ? 'needs_semantic_review' : 'rule_classified_skill_local',
|
|
583
|
+
human_review_evidence: humanEvidence,
|
|
584
|
+
rationale: needsReview
|
|
585
|
+
? 'Provides skill-local checklists/templates adjacent to promoted domain knowledge; flagged as needs_semantic_review for future cross-skill consolidation.'
|
|
586
|
+
: 'Provides skill-local execution steps, report formatting templates, or checklists specific to this skill contract.',
|
|
587
|
+
promoted_to_knowledge_ids: []
|
|
588
|
+
};
|
|
589
|
+
}
|
|
590
|
+
|
|
591
|
+
export function buildSkillArchitectureAuditData(rootDir = DEFAULT_ROOT) {
|
|
592
|
+
const skillsRegistry = readJson(path.join(rootDir, 'registry/skills.json'));
|
|
593
|
+
const knowledgeCatalog = readJson(path.join(rootDir, 'registry/knowledge-catalog.json'));
|
|
594
|
+
const recipeCatalog = readJson(path.join(rootDir, 'registry/recipe-catalog.json'));
|
|
595
|
+
const workflowGraph = readJson(path.join(rootDir, 'registry/workflow-graph.json'));
|
|
596
|
+
const capabilityPolicy = readJson(path.join(rootDir, 'registry/runtime-capability-policy.json'));
|
|
597
|
+
|
|
598
|
+
const capPolicyMap = new Map(
|
|
599
|
+
(capabilityPolicy.skills || []).map((entry) => [entry.skillId, entry])
|
|
600
|
+
);
|
|
601
|
+
|
|
602
|
+
const promotedMap = new Map();
|
|
603
|
+
const skillToKnowledge = new Map();
|
|
604
|
+
const skillToRecipes = new Map();
|
|
605
|
+
|
|
606
|
+
for (const record of knowledgeCatalog.records) {
|
|
607
|
+
for (const refPath of record.promoted_from_skill_refs || []) {
|
|
608
|
+
if (!promotedMap.has(refPath)) promotedMap.set(refPath, []);
|
|
609
|
+
promotedMap.get(refPath).push(record.id);
|
|
610
|
+
}
|
|
611
|
+
for (const skillId of record.related_ids?.skill_ids || []) {
|
|
612
|
+
if (!skillToKnowledge.has(skillId)) skillToKnowledge.set(skillId, []);
|
|
613
|
+
if (!skillToKnowledge.get(skillId).includes(record.id)) {
|
|
614
|
+
skillToKnowledge.get(skillId).push(record.id);
|
|
615
|
+
}
|
|
616
|
+
}
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
for (const recipe of recipeCatalog.recipes) {
|
|
620
|
+
const allSkillIds = new Set([
|
|
621
|
+
...(recipe.required_skill_ids || recipe.required_skills || []),
|
|
622
|
+
...(recipe.optional_skills || [])
|
|
623
|
+
]);
|
|
624
|
+
for (const st of recipe.stages || []) {
|
|
625
|
+
for (const sid of st.skill_ids || []) allSkillIds.add(sid);
|
|
626
|
+
}
|
|
627
|
+
for (const skillId of allSkillIds) {
|
|
628
|
+
if (!skillToRecipes.has(skillId)) skillToRecipes.set(skillId, []);
|
|
629
|
+
if (!skillToRecipes.get(skillId).includes(recipe.id)) {
|
|
630
|
+
skillToRecipes.get(skillId).push(recipe.id);
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
}
|
|
634
|
+
|
|
635
|
+
const allReferenceClassifications = [];
|
|
636
|
+
const classificationCounts = {
|
|
637
|
+
reusable_cross_skill_knowledge: 0,
|
|
638
|
+
skill_specific_operating_instructions: 0,
|
|
639
|
+
recipe_specific_procedure: 0,
|
|
640
|
+
workflow_or_pack_governance: 0,
|
|
641
|
+
historical_or_eval_evidence: 0,
|
|
642
|
+
outdated_or_duplicated: 0
|
|
643
|
+
};
|
|
644
|
+
const classificationMethodCounts = {
|
|
645
|
+
knowledge_promotion_mapping: 0,
|
|
646
|
+
rule_based_governance_and_recipe_mapping: 0,
|
|
647
|
+
rule_based_path_and_heading_inspection: 0,
|
|
648
|
+
human_semantic_review: 0
|
|
649
|
+
};
|
|
650
|
+
let needsSemanticReviewCount = 0;
|
|
651
|
+
|
|
652
|
+
const skillAudits = skillsRegistry.skills.map((skill) => {
|
|
653
|
+
const refsDir = path.join(rootDir, 'skills', skill.id, 'references');
|
|
654
|
+
const refFiles = fs.existsSync(refsDir)
|
|
655
|
+
? fs.readdirSync(refsDir).filter((f) => f.endsWith('.md')).sort()
|
|
656
|
+
: [];
|
|
657
|
+
|
|
658
|
+
const classifiedRefs = refFiles.map((fileName) => {
|
|
659
|
+
const relPath = `skills/${skill.id}/references/${fileName}`;
|
|
660
|
+
const entry = classifyReferenceFile(rootDir, relPath, promotedMap);
|
|
661
|
+
classificationCounts[entry.classification] = (classificationCounts[entry.classification] || 0) + 1;
|
|
662
|
+
classificationMethodCounts[entry.classification_method] =
|
|
663
|
+
(classificationMethodCounts[entry.classification_method] || 0) + 1;
|
|
664
|
+
if (entry.review_status === 'needs_semantic_review') {
|
|
665
|
+
needsSemanticReviewCount += 1;
|
|
666
|
+
}
|
|
667
|
+
allReferenceClassifications.push(entry);
|
|
668
|
+
return entry;
|
|
669
|
+
});
|
|
670
|
+
|
|
671
|
+
const linkedKnowledge = (skillToKnowledge.get(skill.id) || []).sort();
|
|
672
|
+
const linkedRecipes = (skillToRecipes.get(skill.id) || []).sort();
|
|
673
|
+
const mdMeta = readSkillMarkdownMetadata(rootDir, skill.id);
|
|
674
|
+
const capEntry = capPolicyMap.get(skill.id);
|
|
675
|
+
const derivedStage = deriveSkillWorkflowStage(skill);
|
|
676
|
+
const governedCeiling = capEntry?.governedRuntimeCeiling || skill.capabilityTier || 'L0';
|
|
677
|
+
|
|
678
|
+
return {
|
|
679
|
+
skill_id: skill.id,
|
|
680
|
+
version: skill.version || '1.0.0',
|
|
681
|
+
display_name: mdMeta.display_name,
|
|
682
|
+
category: skill.category,
|
|
683
|
+
contract_role: skill.role,
|
|
684
|
+
purpose: skill.purpose,
|
|
685
|
+
frontmatter_description: mdMeta.frontmatter_description,
|
|
686
|
+
derived_workflow_stage: derivedStage,
|
|
687
|
+
workflow_stage: derivedStage,
|
|
688
|
+
workflow_stage_is_derived: true,
|
|
689
|
+
capability_tier: skill.capabilityTier,
|
|
690
|
+
governed_runtime_ceiling: governedCeiling,
|
|
691
|
+
mutates_scene: governedCeiling !== 'L0',
|
|
692
|
+
requires_pre_mutation_backup_when_executed: Boolean(capEntry?.requiresPreMutationBackupWhenExecuted),
|
|
693
|
+
laws_enforced: mdMeta.laws_referenced,
|
|
694
|
+
primary_layer: 'skill-layer',
|
|
695
|
+
current_role_classification: classifySkillRole(skill),
|
|
696
|
+
recommended_disposition: 'keep_as_skill_and_link_knowledge',
|
|
697
|
+
linked_knowledge_ids: linkedKnowledge,
|
|
698
|
+
linked_recipe_ids: linkedRecipes,
|
|
699
|
+
reference_files_count: classifiedRefs.length,
|
|
700
|
+
references: classifiedRefs
|
|
701
|
+
};
|
|
702
|
+
});
|
|
703
|
+
|
|
704
|
+
// Historical / evaluation evidence files stored in their canonical layer (docs/evals/ & docs/audits/)
|
|
705
|
+
const docsEvalsDir = path.join(rootDir, 'docs/evals');
|
|
706
|
+
const historicalEvalFilesCount = fs.existsSync(docsEvalsDir)
|
|
707
|
+
? fs.readdirSync(docsEvalsDir).filter((f) => f.endsWith('.md') && f !== 'README.md').length
|
|
708
|
+
: 0;
|
|
709
|
+
|
|
710
|
+
return {
|
|
711
|
+
schema_version: '1.1.0',
|
|
712
|
+
audit_scope: 'five-layer-architecture-reconciliation',
|
|
713
|
+
workflow_stage_derivation_rule: WORKFLOW_STAGE_DERIVATION_RULE,
|
|
714
|
+
classification_methodology: {
|
|
715
|
+
summary: `Combines explicit promoted_from_skill_refs mappings (${classificationMethodCounts.knowledge_promotion_mapping} files), rule-based governance & recipe prefix mappings (${classificationMethodCounts.rule_based_governance_and_recipe_mapping} files), rule-based path + heading inspection of skill-local operating instructions (${classificationMethodCounts.rule_based_path_and_heading_inspection} files), and verified human semantic reviews (${classificationMethodCounts.human_semantic_review} files — requires traceable reviewer, timestamp, scope, and outcome evidence).`,
|
|
716
|
+
methods_breakdown: classificationMethodCounts,
|
|
717
|
+
needs_semantic_review_count: needsSemanticReviewCount,
|
|
718
|
+
historical_eval_evidence_files_in_docs_evals: historicalEvalFilesCount,
|
|
719
|
+
honesty_note:
|
|
720
|
+
'outdated_or_duplicated is 0 for exact file hash collisions inside skills/*/references/*.md; 8 skill-local checklist references that border promoted domain topics are explicitly marked review_status="needs_semantic_review", and rule-based prefix classifications are never represented as human_semantic_review without traceable reviewer/timestamp/scope/outcome evidence.'
|
|
721
|
+
},
|
|
722
|
+
five_layer_architecture: {
|
|
723
|
+
skill_layer: {
|
|
724
|
+
canonical_paths: ['skills/*/SKILL.md', 'skills/*/contract.json', 'registry/skills.json', 'registry/workflow-graph.json'],
|
|
725
|
+
skill_count: skillAudits.length,
|
|
726
|
+
workflow_edge_count: (workflowGraph.edges || []).length
|
|
727
|
+
},
|
|
728
|
+
knowledge_layer: {
|
|
729
|
+
canonical_paths: ['registry/knowledge-sources.json', 'registry/knowledge-catalog.json', 'schemas/knowledge-record.schema.json', 'schemas/knowledge-source-registry.schema.json'],
|
|
730
|
+
domain_count: REQUIRED_DOMAINS.length,
|
|
731
|
+
source_count: readJson(path.join(rootDir, 'registry/knowledge-sources.json')).sources.length,
|
|
732
|
+
knowledge_record_count: knowledgeCatalog.records.length
|
|
733
|
+
},
|
|
734
|
+
recipe_layer: {
|
|
735
|
+
canonical_paths: ['registry/recipe-catalog.json', 'schemas/recipe-record.schema.json', 'docs/recipes/'],
|
|
736
|
+
recipe_count: recipeCatalog.recipes.length,
|
|
737
|
+
scenario_recipes: ['docs/recipes/cyberpunk-shoe-hero.md']
|
|
738
|
+
},
|
|
739
|
+
runtime_production_layer: {
|
|
740
|
+
status: 'external-boundary-only',
|
|
741
|
+
paths_supported: [
|
|
742
|
+
'Path 1: Official Blender Lab MCP (Blender 5.1+ Lab add-on + server)',
|
|
743
|
+
'Path 2: Community mcp-for-blender (Blender 3.0+)',
|
|
744
|
+
'CLI Appendix: blender --background --python'
|
|
745
|
+
],
|
|
746
|
+
capability_policy_path: 'registry/runtime-capability-policy.json'
|
|
747
|
+
},
|
|
748
|
+
evaluation_and_evidence_layer: {
|
|
749
|
+
canonical_paths: ['evals/suites/*.eval.json', 'evals/catalog-retrieval-evals.json', 'evals/scene-specs/', 'docs/evals/', 'docs/audits/'],
|
|
750
|
+
runtime_execution_truth_state: 'Not Run',
|
|
751
|
+
artifact_production_truth_state: 'Not Produced'
|
|
752
|
+
}
|
|
753
|
+
},
|
|
754
|
+
summary: {
|
|
755
|
+
total_skills_audited: skillAudits.length,
|
|
756
|
+
total_skill_references_classified: allReferenceClassifications.length,
|
|
757
|
+
reference_classification_breakdown: classificationCounts,
|
|
758
|
+
classification_method_breakdown: classificationMethodCounts,
|
|
759
|
+
needs_semantic_review_count: needsSemanticReviewCount,
|
|
760
|
+
skills_with_linked_knowledge: skillAudits.filter((s) => s.linked_knowledge_ids.length > 0).length,
|
|
761
|
+
skills_with_linked_recipes: skillAudits.filter((s) => s.linked_recipe_ids.length > 0).length
|
|
762
|
+
},
|
|
763
|
+
skills: skillAudits,
|
|
764
|
+
reference_classifications: allReferenceClassifications
|
|
765
|
+
};
|
|
766
|
+
}
|
|
767
|
+
|
|
768
|
+
export function renderSkillArchitectureAuditMarkdown(auditData) {
|
|
769
|
+
const lines = [
|
|
770
|
+
'# BlendOps — Skill Architecture & Reference Classification Audit',
|
|
771
|
+
'',
|
|
772
|
+
'> Generated deterministically by `scripts/build-knowledge-catalog.mjs`. Maps all 48 canonical skills from `registry/skills.json` and `registry/runtime-capability-policy.json`, and classifies all 151 `skills/*/references/*.md` files across the 5-layer architecture.',
|
|
773
|
+
'',
|
|
774
|
+
'## 1. Five-Layer Architecture Summary',
|
|
775
|
+
'',
|
|
776
|
+
'| Layer | Canonical Artifacts | Count / Status | Responsibility |',
|
|
777
|
+
'| :--- | :--- | :--- | :--- |',
|
|
778
|
+
`| **A. Skill Layer** | \`skills/*/SKILL.md\`, \`skills/*/contract.json\`, \`registry/skills.json\`, \`registry/workflow-graph.json\` | ${auditData.five_layer_architecture.skill_layer.skill_count} skills, ${auditData.five_layer_architecture.skill_layer.workflow_edge_count} workflow edges | Single-responsibility agent task units, contracts, capability tiers (\`L0\`–\`L3\`), and handoffs |`,
|
|
779
|
+
`| **B. Knowledge Layer** | \`registry/knowledge-sources.json\`, \`registry/knowledge-catalog.json\` | ${auditData.five_layer_architecture.knowledge_layer.knowledge_record_count} records across ${auditData.five_layer_architecture.knowledge_layer.domain_count} domains (${auditData.five_layer_architecture.knowledge_layer.source_count} sources) | Reusable, source-traceable 3D/Blender domain rules, parameters, tradeoffs, and validation checks |`,
|
|
780
|
+
`| **C. Recipe Layer** | \`registry/recipe-catalog.json\`, \`docs/recipes/cyberpunk-shoe-hero.md\` | ${auditData.five_layer_architecture.recipe_layer.recipe_count} canonical recipes + 1 golden-path scenario doc | Multi-stage asset/scene construction plans composing skills, knowledge records, and checkpoints |`,
|
|
781
|
+
`| **D. Runtime / Production Layer** | \`registry/runtime-capability-policy.json\`, \`docs/runtime-stack-strategy.md\` | External boundary (Path 1 Lab MCP 5.1+, Path 2 \`mcp-for-blender\` 3.0+, CLI appendix) | External execution bridges; BlendOps owns zero runtime servers or add-ons |`,
|
|
782
|
+
`| **E. Evaluation & Evidence Layer** | \`evals/suites/\`, \`evals/catalog-retrieval-evals.json\`, \`evals/scene-specs/\`, \`docs/evals/\` | Offline contract + retrieval + planner evals passing; runtime = \`${auditData.five_layer_architecture.evaluation_and_evidence_layer.runtime_execution_truth_state}\`, artifacts = \`${auditData.five_layer_architecture.evaluation_and_evidence_layer.artifact_production_truth_state}\` | Separates schema validity, source backing, version checks, runtime execution, and visual critique |`,
|
|
783
|
+
'',
|
|
784
|
+
'## 2. Skill Reference Classification & Methodology Summary (151 Files)',
|
|
785
|
+
'',
|
|
786
|
+
`- **Derivation Rule for Workflow Stages**: ${auditData.workflow_stage_derivation_rule}`,
|
|
787
|
+
`- **Classification Methodology**: ${auditData.classification_methodology.summary}`,
|
|
788
|
+
`- **Honesty Note**: ${auditData.classification_methodology.honesty_note}`,
|
|
789
|
+
'',
|
|
790
|
+
'| Classification Category | File Count | Primary Method | Description |',
|
|
791
|
+
'| :--- | ---: | :--- | :--- |',
|
|
792
|
+
`| \`reusable_cross_skill_knowledge\` | ${auditData.summary.reference_classification_breakdown.reusable_cross_skill_knowledge} | \`knowledge_promotion_mapping\` | Domain rules promoted to canonical \`knowledge.*\` records in \`registry/knowledge-catalog.json\` |`,
|
|
793
|
+
`| \`skill_specific_operating_instructions\` | ${auditData.summary.reference_classification_breakdown.skill_specific_operating_instructions} | \`rule_based_path_and_heading_inspection\` (${auditData.summary.needs_semantic_review_count} flagged \`needs_semantic_review\`) | Skill-local checklists, report templates, and step-by-step operating instructions |`,
|
|
794
|
+
`| \`workflow_or_pack_governance\` | ${auditData.summary.reference_classification_breakdown.workflow_or_pack_governance} | \`rule_based_governance_and_recipe_mapping\` | Stage routing, intake clarification, pack prerequisite, stage gates, and runtime path governance |`,
|
|
795
|
+
`| \`recipe_specific_procedure\` | ${auditData.summary.reference_classification_breakdown.recipe_specific_procedure} | \`rule_based_governance_and_recipe_mapping\` | Recipe discovery catalog and recipe decomposition rules synchronized with \`registry/recipe-catalog.json\` |`,
|
|
796
|
+
`| \`historical_or_eval_evidence\` | ${auditData.summary.reference_classification_breakdown.historical_or_eval_evidence} | Stored in \`docs/evals/\` (${auditData.classification_methodology.historical_eval_evidence_files_in_docs_evals} files) | Historical evaluation and runtime evidence records live under \`docs/evals/\` rather than inside \`skills/*/references/\` |`,
|
|
797
|
+
`| \`outdated_or_duplicated\` | ${auditData.summary.reference_classification_breakdown.outdated_or_duplicated} | Exact hash & promotion audit | Zero exact duplicate reference files; ${auditData.summary.needs_semantic_review_count} adjacent checklist files tracked under \`needs_semantic_review\` |`,
|
|
798
|
+
`| **Total** | **${auditData.summary.total_skill_references_classified}** | **100% accounted for** | **All 151 \`skills/*/references/*.md\` files classified with zero \`undefined\` fields** |`,
|
|
799
|
+
'',
|
|
800
|
+
'## 3. Complete 48-Skill Architecture Matrix',
|
|
801
|
+
'',
|
|
802
|
+
'| # | Skill ID | Category | Derived Stage | Capability Tier (Ceiling) | Role Classification | Disposition | Linked Knowledge | Linked Recipes | Refs |',
|
|
803
|
+
'| ---: | :--- | :--- | :--- | :--- | :--- | :--- | ---: | ---: | ---: |'
|
|
804
|
+
];
|
|
805
|
+
|
|
806
|
+
auditData.skills.forEach((s, idx) => {
|
|
807
|
+
lines.push(
|
|
808
|
+
`| ${idx + 1} | \`${s.skill_id}\` | \`${s.category}\` | \`${s.derived_workflow_stage}\` | \`${s.capability_tier}\` (\`${s.governed_runtime_ceiling}\`) | \`${s.current_role_classification}\` | \`${s.recommended_disposition}\` | ${s.linked_knowledge_ids.length} | ${s.linked_recipe_ids.length} | ${s.reference_files_count} |`
|
|
809
|
+
);
|
|
810
|
+
});
|
|
811
|
+
|
|
812
|
+
lines.push(
|
|
813
|
+
'',
|
|
814
|
+
'## 4. Promoted Cross-Skill Reference Files -> Canonical Knowledge Records',
|
|
815
|
+
'',
|
|
816
|
+
'| Reference File Path | Title | Classification | Method | Promoted To Canonical `knowledge.*` ID(s) |',
|
|
817
|
+
'| :--- | :--- | :--- | :--- | :--- |'
|
|
818
|
+
);
|
|
819
|
+
|
|
820
|
+
for (const ref of auditData.reference_classifications) {
|
|
821
|
+
if (ref.promoted_to_knowledge_ids.length > 0 || ref.classification === 'recipe_specific_procedure') {
|
|
822
|
+
const targets = ref.promoted_to_knowledge_ids.length > 0
|
|
823
|
+
? ref.promoted_to_knowledge_ids.map((id) => `\`${id}\``).join(', ')
|
|
824
|
+
: 'Synchronized with `registry/recipe-catalog.json`';
|
|
825
|
+
lines.push(`| \`${ref.path}\` | ${ref.title} | \`${ref.classification}\` | \`${ref.classification_method}\` | ${targets} |`);
|
|
826
|
+
}
|
|
827
|
+
}
|
|
828
|
+
|
|
829
|
+
lines.push('');
|
|
830
|
+
return lines.join('\n');
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
export const generateSkillArchitectureAuditData = buildSkillArchitectureAuditData;
|
|
834
|
+
|
|
835
|
+
/**
|
|
836
|
+
* Compiles a real JSON Schema Draft 2020-12 validator using Ajv2020.
|
|
837
|
+
*/
|
|
838
|
+
export function compileSchemaValidator(rootSchema) {
|
|
839
|
+
const ajv = new Ajv2020({ allErrors: true, strict: false });
|
|
840
|
+
return ajv.compile(rootSchema);
|
|
841
|
+
}
|
|
842
|
+
|
|
843
|
+
/**
|
|
844
|
+
* Evaluates whether a knowledge record or recipe record is eligible for its declared `evidence_status`.
|
|
845
|
+
* Specifically enforces that `runtime-tested` is only allowed when backed by a real, non-static,
|
|
846
|
+
* schema-validated runtime evidence packet recording actual Blender version, MCP/CLI procedure,
|
|
847
|
+
* Produced/Verified status, and artifact hashes.
|
|
848
|
+
*/
|
|
849
|
+
export function evaluateEvidencePromotionGate(recordOrRecipe, rootDir = DEFAULT_ROOT) {
|
|
850
|
+
const errors = [];
|
|
851
|
+
const status = recordOrRecipe?.evidence_status;
|
|
852
|
+
const id = recordOrRecipe?.id || '(unknown-id)';
|
|
853
|
+
|
|
854
|
+
if (!['authored', 'source-reviewed', 'version-checked', 'runtime-tested'].includes(status)) {
|
|
855
|
+
return {
|
|
856
|
+
allowed: false,
|
|
857
|
+
status,
|
|
858
|
+
errors: [`Record ${id} has invalid evidence_status "${status}".`]
|
|
859
|
+
};
|
|
860
|
+
}
|
|
861
|
+
|
|
862
|
+
if (status !== 'runtime-tested') {
|
|
863
|
+
if (recordOrRecipe?.blender_versions?.runtime_tested_version) {
|
|
864
|
+
errors.push(
|
|
865
|
+
`Record ${id} has evidence_status="${status}" (not runtime-tested), so blender_versions.runtime_tested_version must be null (got "${recordOrRecipe.blender_versions.runtime_tested_version}").`
|
|
866
|
+
);
|
|
867
|
+
}
|
|
868
|
+
return {
|
|
869
|
+
allowed: errors.length === 0,
|
|
870
|
+
status,
|
|
871
|
+
errors
|
|
872
|
+
};
|
|
873
|
+
}
|
|
874
|
+
|
|
875
|
+
const relPacketPath = recordOrRecipe.evidence_packet_path;
|
|
876
|
+
if (!relPacketPath || typeof relPacketPath !== 'string' || !/^docs\/evals\/[a-z0-9._-]+\.(md|json)$/.test(relPacketPath)) {
|
|
877
|
+
errors.push(
|
|
878
|
+
`Record ${id} claims evidence_status="runtime-tested" without a valid evidence_packet_path under docs/evals/*.json or docs/evals/*.md.`
|
|
879
|
+
);
|
|
880
|
+
return { allowed: false, status, errors };
|
|
881
|
+
}
|
|
882
|
+
|
|
883
|
+
const absPacketPath = path.join(rootDir, relPacketPath);
|
|
884
|
+
if (!fs.existsSync(absPacketPath)) {
|
|
885
|
+
errors.push(
|
|
886
|
+
`Record ${id} claims evidence_status="runtime-tested", but evidence_packet_path "${relPacketPath}" does not exist on disk.`
|
|
887
|
+
);
|
|
888
|
+
return { allowed: false, status, errors };
|
|
889
|
+
}
|
|
890
|
+
|
|
891
|
+
const rawContent = fs.readFileSync(absPacketPath, 'utf8');
|
|
892
|
+
let packetObj = null;
|
|
893
|
+
|
|
894
|
+
if (relPacketPath.endsWith('.json')) {
|
|
895
|
+
try {
|
|
896
|
+
packetObj = JSON.parse(rawContent);
|
|
897
|
+
} catch (err) {
|
|
898
|
+
errors.push(`Record ${id} evidence_packet_path "${relPacketPath}" contains malformed JSON: ${err.message}`);
|
|
899
|
+
return { allowed: false, status, errors };
|
|
900
|
+
}
|
|
901
|
+
} else {
|
|
902
|
+
// Markdown eval file: check if it embeds a JSON runtime-evidence-packet block
|
|
903
|
+
const jsonBlockMatch = rawContent.match(/```json\s*([\s\S]*?)```/);
|
|
904
|
+
if (jsonBlockMatch) {
|
|
905
|
+
try {
|
|
906
|
+
const candidate = JSON.parse(jsonBlockMatch[1]);
|
|
907
|
+
if (candidate && typeof candidate === 'object' && candidate.runtimeEvidence && candidate.artifactEvidence) {
|
|
908
|
+
packetObj = candidate;
|
|
909
|
+
}
|
|
910
|
+
} catch {
|
|
911
|
+
packetObj = null;
|
|
912
|
+
}
|
|
913
|
+
}
|
|
914
|
+
if (!packetObj) {
|
|
915
|
+
errors.push(
|
|
916
|
+
`Record ${id} claims evidence_status="runtime-tested" pointing to "${relPacketPath}", which does not contain a machine-validated live runtime evidence packet (runtime remains Not Run).`
|
|
917
|
+
);
|
|
918
|
+
return { allowed: false, status, errors };
|
|
919
|
+
}
|
|
920
|
+
}
|
|
921
|
+
|
|
922
|
+
const packetVal = validateEvidencePacket(packetObj);
|
|
923
|
+
if (!packetVal.valid) {
|
|
924
|
+
errors.push(
|
|
925
|
+
`Record ${id} runtime evidence packet "${relPacketPath}" failed schema/policy validation: ${packetVal.errors.join('; ')}`
|
|
926
|
+
);
|
|
927
|
+
return { allowed: false, status, errors };
|
|
928
|
+
}
|
|
929
|
+
|
|
930
|
+
if (packetObj.isStaticFixture === true) {
|
|
931
|
+
errors.push(
|
|
932
|
+
`Record ${id} cannot promote to evidence_status="runtime-tested" using a static CI fixture (isStaticFixture: true in "${relPacketPath}").`
|
|
933
|
+
);
|
|
934
|
+
}
|
|
935
|
+
|
|
936
|
+
const rtStatus = packetObj.runtimeEvidence?.runtimeStatus;
|
|
937
|
+
if (rtStatus !== 'Produced' && rtStatus !== 'Verified') {
|
|
938
|
+
errors.push(
|
|
939
|
+
`Record ${id} cannot promote to evidence_status="runtime-tested" when runtimeEvidence.runtimeStatus is "${rtStatus}" (requires "Produced" or "Verified").`
|
|
940
|
+
);
|
|
941
|
+
}
|
|
942
|
+
|
|
943
|
+
const testedVer = packetObj.runtimeEvidence?.blenderVersion;
|
|
944
|
+
if (!testedVer) {
|
|
945
|
+
errors.push(
|
|
946
|
+
`Record ${id} runtime evidence packet "${relPacketPath}" is missing runtimeEvidence.blenderVersion.`
|
|
947
|
+
);
|
|
948
|
+
} else if (
|
|
949
|
+
recordOrRecipe.blender_versions &&
|
|
950
|
+
recordOrRecipe.blender_versions.runtime_tested_version !== testedVer
|
|
951
|
+
) {
|
|
952
|
+
errors.push(
|
|
953
|
+
`Record ${id} blender_versions.runtime_tested_version ("${recordOrRecipe.blender_versions.runtime_tested_version}") does not match evidence packet blenderVersion ("${testedVer}").`
|
|
954
|
+
);
|
|
955
|
+
}
|
|
956
|
+
|
|
957
|
+
return {
|
|
958
|
+
allowed: errors.length === 0,
|
|
959
|
+
status,
|
|
960
|
+
errors,
|
|
961
|
+
packet: packetObj
|
|
962
|
+
};
|
|
963
|
+
}
|
|
964
|
+
|
|
965
|
+
export function validateKnowledgeAndRecipeCatalogs(rootDir = DEFAULT_ROOT) {
|
|
966
|
+
const errors = [];
|
|
967
|
+
const warnings = [];
|
|
968
|
+
const paths = resolveCatalogPaths(rootDir);
|
|
969
|
+
|
|
970
|
+
for (const p of [
|
|
971
|
+
paths.sourcesSchemaPath,
|
|
972
|
+
paths.knowledgeSchemaPath,
|
|
973
|
+
paths.recipeSchemaPath,
|
|
974
|
+
paths.sourcesPath,
|
|
975
|
+
paths.knowledgePath,
|
|
976
|
+
paths.recipesPath,
|
|
977
|
+
paths.skillsPath
|
|
978
|
+
]) {
|
|
979
|
+
if (!fs.existsSync(p)) {
|
|
980
|
+
errors.push(`Missing required file: ${path.relative(rootDir, p)}`);
|
|
981
|
+
}
|
|
982
|
+
}
|
|
983
|
+
if (errors.length > 0) {
|
|
984
|
+
return { valid: false, errors, warnings };
|
|
985
|
+
}
|
|
986
|
+
|
|
987
|
+
const validateSources = compileSchemaValidator(readJson(paths.sourcesSchemaPath));
|
|
988
|
+
const validateKnowledge = compileSchemaValidator(readJson(paths.knowledgeSchemaPath));
|
|
989
|
+
const validateRecipes = compileSchemaValidator(readJson(paths.recipeSchemaPath));
|
|
990
|
+
|
|
991
|
+
const sourcesData = readJson(paths.sourcesPath);
|
|
992
|
+
const knowledgeData = readJson(paths.knowledgePath);
|
|
993
|
+
const recipesData = readJson(paths.recipesPath);
|
|
994
|
+
const skillsData = readJson(paths.skillsPath);
|
|
995
|
+
|
|
996
|
+
if (!validateSources(sourcesData)) {
|
|
997
|
+
for (const err of validateSources.errors || []) {
|
|
998
|
+
errors.push(`registry/knowledge-sources.json ${err.instancePath || '/'}: ${err.message}`);
|
|
999
|
+
}
|
|
1000
|
+
}
|
|
1001
|
+
if (!validateKnowledge(knowledgeData)) {
|
|
1002
|
+
for (const err of validateKnowledge.errors || []) {
|
|
1003
|
+
errors.push(`registry/knowledge-catalog.json ${err.instancePath || '/'}: ${err.message}`);
|
|
1004
|
+
}
|
|
1005
|
+
}
|
|
1006
|
+
if (!validateRecipes(recipesData)) {
|
|
1007
|
+
for (const err of validateRecipes.errors || []) {
|
|
1008
|
+
errors.push(`registry/recipe-catalog.json ${err.instancePath || '/'}: ${err.message}`);
|
|
1009
|
+
}
|
|
1010
|
+
}
|
|
1011
|
+
|
|
1012
|
+
const sourceIds = new Set();
|
|
1013
|
+
for (const src of sourcesData.sources || []) {
|
|
1014
|
+
if (sourceIds.has(src.id)) {
|
|
1015
|
+
errors.push(`Duplicate source ID: ${src.id}`);
|
|
1016
|
+
}
|
|
1017
|
+
sourceIds.add(src.id);
|
|
1018
|
+
}
|
|
1019
|
+
|
|
1020
|
+
const skillIds = new Set((skillsData.skills || []).map((s) => s.id));
|
|
1021
|
+
const knowledgeIds = new Set();
|
|
1022
|
+
const domainCounts = new Map(REQUIRED_DOMAINS.map((d) => [d, 0]));
|
|
1023
|
+
|
|
1024
|
+
for (const rec of knowledgeData.records || []) {
|
|
1025
|
+
if (knowledgeIds.has(rec.id)) {
|
|
1026
|
+
errors.push(`Duplicate knowledge ID: ${rec.id}`);
|
|
1027
|
+
}
|
|
1028
|
+
knowledgeIds.add(rec.id);
|
|
1029
|
+
domainCounts.set(rec.domain, (domainCounts.get(rec.domain) || 0) + 1);
|
|
1030
|
+
}
|
|
1031
|
+
|
|
1032
|
+
for (const domain of REQUIRED_DOMAINS) {
|
|
1033
|
+
const count = domainCounts.get(domain) || 0;
|
|
1034
|
+
if (count < 2) {
|
|
1035
|
+
errors.push(`Domain "${domain}" has ${count} knowledge records; at least 2 are required.`);
|
|
1036
|
+
}
|
|
1037
|
+
}
|
|
1038
|
+
|
|
1039
|
+
const recipeIds = new Set();
|
|
1040
|
+
for (const rec of recipesData.recipes || []) {
|
|
1041
|
+
if (recipeIds.has(rec.id)) {
|
|
1042
|
+
errors.push(`Duplicate recipe ID: ${rec.id}`);
|
|
1043
|
+
}
|
|
1044
|
+
recipeIds.add(rec.id);
|
|
1045
|
+
}
|
|
1046
|
+
|
|
1047
|
+
for (const reqRecipeId of REQUIRED_RECIPE_IDS) {
|
|
1048
|
+
if (!recipeIds.has(reqRecipeId)) {
|
|
1049
|
+
errors.push(`Missing required canonical recipe ID: ${reqRecipeId}`);
|
|
1050
|
+
}
|
|
1051
|
+
}
|
|
1052
|
+
|
|
1053
|
+
const placeholderRegex = /\b(TODO|TBD|FIXME|lorem ipsum)\b/i;
|
|
1054
|
+
|
|
1055
|
+
// Cross-reference & evidence-gate validation for knowledge records
|
|
1056
|
+
for (const rec of knowledgeData.records || []) {
|
|
1057
|
+
if (placeholderRegex.test(JSON.stringify(rec))) {
|
|
1058
|
+
errors.push(`Knowledge record ${rec.id} contains placeholder text (TODO/TBD/FIXME).`);
|
|
1059
|
+
}
|
|
1060
|
+
const gateRes = evaluateEvidencePromotionGate(rec, paths.baseDir);
|
|
1061
|
+
if (!gateRes.allowed) {
|
|
1062
|
+
for (const ge of gateRes.errors) errors.push(ge);
|
|
1063
|
+
}
|
|
1064
|
+
for (const sr of rec.source_refs || []) {
|
|
1065
|
+
if (!sourceIds.has(sr.source_id)) {
|
|
1066
|
+
errors.push(`Knowledge record ${rec.id} references unknown source_id "${sr.source_id}".`);
|
|
1067
|
+
}
|
|
1068
|
+
}
|
|
1069
|
+
for (const claim of rec.claims || []) {
|
|
1070
|
+
for (const sr of claim.source_refs || []) {
|
|
1071
|
+
if (!sourceIds.has(sr.source_id)) {
|
|
1072
|
+
errors.push(`Knowledge record ${rec.id} claim ${claim.id} references unknown source_id "${sr.source_id}".`);
|
|
1073
|
+
}
|
|
1074
|
+
}
|
|
1075
|
+
}
|
|
1076
|
+
for (const kid of rec.related_ids?.knowledge_ids || []) {
|
|
1077
|
+
if (!knowledgeIds.has(kid)) {
|
|
1078
|
+
errors.push(`Knowledge record ${rec.id} references unknown related knowledge_id "${kid}".`);
|
|
1079
|
+
}
|
|
1080
|
+
if (kid === rec.id) {
|
|
1081
|
+
errors.push(`Knowledge record ${rec.id} self-references "${kid}" in related_ids.knowledge_ids.`);
|
|
1082
|
+
}
|
|
1083
|
+
}
|
|
1084
|
+
for (const sid of rec.related_ids?.skill_ids || []) {
|
|
1085
|
+
if (!skillIds.has(sid)) {
|
|
1086
|
+
errors.push(`Knowledge record ${rec.id} references unknown skill_id "${sid}".`);
|
|
1087
|
+
}
|
|
1088
|
+
}
|
|
1089
|
+
for (const rid of rec.related_ids?.recipe_ids || []) {
|
|
1090
|
+
if (!recipeIds.has(rid)) {
|
|
1091
|
+
errors.push(`Knowledge record ${rec.id} references unknown recipe_id "${rid}".`);
|
|
1092
|
+
}
|
|
1093
|
+
}
|
|
1094
|
+
for (const refPath of rec.promoted_from_skill_refs || []) {
|
|
1095
|
+
const fullPath = path.join(paths.baseDir, refPath);
|
|
1096
|
+
if (fs.existsSync(path.join(paths.baseDir, 'skills')) && !fs.existsSync(fullPath)) {
|
|
1097
|
+
errors.push(`Knowledge record ${rec.id} promoted_from_skill_refs path does not exist: ${refPath}`);
|
|
1098
|
+
}
|
|
1099
|
+
}
|
|
1100
|
+
}
|
|
1101
|
+
|
|
1102
|
+
// Cross-reference & evidence-gate validation for recipes
|
|
1103
|
+
for (const recipe of recipesData.recipes || []) {
|
|
1104
|
+
if (placeholderRegex.test(JSON.stringify(recipe))) {
|
|
1105
|
+
errors.push(`Recipe ${recipe.id} contains placeholder text (TODO/TBD/FIXME).`);
|
|
1106
|
+
}
|
|
1107
|
+
const gateRes = evaluateEvidencePromotionGate(recipe, paths.baseDir);
|
|
1108
|
+
if (!gateRes.allowed) {
|
|
1109
|
+
for (const ge of gateRes.errors) errors.push(ge);
|
|
1110
|
+
}
|
|
1111
|
+
for (const sid of [...(recipe.required_skill_ids || []), ...(recipe.optional_skills || [])]) {
|
|
1112
|
+
if (!skillIds.has(sid)) {
|
|
1113
|
+
errors.push(`Recipe ${recipe.id} references unknown skill_id "${sid}".`);
|
|
1114
|
+
}
|
|
1115
|
+
}
|
|
1116
|
+
for (const kid of recipe.required_knowledge_ids || []) {
|
|
1117
|
+
if (!knowledgeIds.has(kid)) {
|
|
1118
|
+
errors.push(`Recipe ${recipe.id} references unknown knowledge_id "${kid}" in required_knowledge_ids.`);
|
|
1119
|
+
}
|
|
1120
|
+
}
|
|
1121
|
+
for (const stage of recipe.stages || []) {
|
|
1122
|
+
for (const sid of stage.skill_ids || []) {
|
|
1123
|
+
if (!skillIds.has(sid)) {
|
|
1124
|
+
errors.push(`Recipe ${recipe.id} stage ${stage.id} references unknown skill_id "${sid}".`);
|
|
1125
|
+
}
|
|
1126
|
+
}
|
|
1127
|
+
for (const kid of stage.knowledge_ids || []) {
|
|
1128
|
+
if (!knowledgeIds.has(kid)) {
|
|
1129
|
+
errors.push(`Recipe ${recipe.id} stage ${stage.id} references unknown knowledge_id "${kid}".`);
|
|
1130
|
+
}
|
|
1131
|
+
}
|
|
1132
|
+
}
|
|
1133
|
+
for (const fm of recipe.failure_modes || []) {
|
|
1134
|
+
if (fm.fallback_skill_id && !skillIds.has(fm.fallback_skill_id)) {
|
|
1135
|
+
errors.push(`Recipe ${recipe.id} failure_mode references unknown fallback_skill_id "${fm.fallback_skill_id}".`);
|
|
1136
|
+
}
|
|
1137
|
+
}
|
|
1138
|
+
for (const relRec of recipe.related_recipes || []) {
|
|
1139
|
+
if (!recipeIds.has(relRec)) {
|
|
1140
|
+
errors.push(`Recipe ${recipe.id} references unknown related_recipe "${relRec}".`);
|
|
1141
|
+
}
|
|
1142
|
+
}
|
|
1143
|
+
for (const sr of recipe.source_refs || []) {
|
|
1144
|
+
if (!sourceIds.has(sr.source_id)) {
|
|
1145
|
+
errors.push(`Recipe ${recipe.id} references unknown source_id "${sr.source_id}".`);
|
|
1146
|
+
}
|
|
1147
|
+
}
|
|
1148
|
+
if (recipe.documentation_path) {
|
|
1149
|
+
const fullPath = path.join(paths.baseDir, recipe.documentation_path);
|
|
1150
|
+
if (fs.existsSync(path.join(paths.baseDir, 'docs/recipes')) && !fs.existsSync(fullPath)) {
|
|
1151
|
+
errors.push(`Recipe ${recipe.id} references missing documentation_path: ${recipe.documentation_path}`);
|
|
1152
|
+
}
|
|
1153
|
+
}
|
|
1154
|
+
}
|
|
1155
|
+
|
|
1156
|
+
return {
|
|
1157
|
+
valid: errors.length === 0,
|
|
1158
|
+
errors,
|
|
1159
|
+
warnings,
|
|
1160
|
+
catalog_mode: paths.mode,
|
|
1161
|
+
counts: {
|
|
1162
|
+
sources: sourceIds.size,
|
|
1163
|
+
knowledge_records: knowledgeIds.size,
|
|
1164
|
+
recipes: recipeIds.size,
|
|
1165
|
+
domains: domainCounts.size,
|
|
1166
|
+
skills: skillIds.size
|
|
1167
|
+
}
|
|
1168
|
+
};
|
|
1169
|
+
}
|
|
1170
|
+
|
|
1171
|
+
export function generateCatalogIndexData(rootDir = DEFAULT_ROOT) {
|
|
1172
|
+
const paths = resolveCatalogPaths(rootDir);
|
|
1173
|
+
const sourcesData = readJson(paths.sourcesPath);
|
|
1174
|
+
const knowledgeData = readJson(paths.knowledgePath);
|
|
1175
|
+
const recipesData = readJson(paths.recipesPath);
|
|
1176
|
+
const skillsData = readJson(paths.skillsPath);
|
|
1177
|
+
|
|
1178
|
+
const byDomain = {};
|
|
1179
|
+
const byKind = {};
|
|
1180
|
+
const bySkillId = {};
|
|
1181
|
+
const byRecipeId = {};
|
|
1182
|
+
const bySourceId = {};
|
|
1183
|
+
const byBlenderVersion = {};
|
|
1184
|
+
const byEvidenceStatus = {};
|
|
1185
|
+
|
|
1186
|
+
for (const d of REQUIRED_DOMAINS) {
|
|
1187
|
+
byDomain[d] = { knowledge_ids: [], recipe_ids: [] };
|
|
1188
|
+
}
|
|
1189
|
+
|
|
1190
|
+
const entries = [];
|
|
1191
|
+
|
|
1192
|
+
for (const rec of knowledgeData.records) {
|
|
1193
|
+
byDomain[rec.domain] = byDomain[rec.domain] || { knowledge_ids: [], recipe_ids: [] };
|
|
1194
|
+
byDomain[rec.domain].knowledge_ids.push(rec.id);
|
|
1195
|
+
|
|
1196
|
+
byKind[rec.kind] = byKind[rec.kind] || [];
|
|
1197
|
+
byKind[rec.kind].push(rec.id);
|
|
1198
|
+
|
|
1199
|
+
byEvidenceStatus[rec.evidence_status] = byEvidenceStatus[rec.evidence_status] || [];
|
|
1200
|
+
byEvidenceStatus[rec.evidence_status].push(rec.id);
|
|
1201
|
+
|
|
1202
|
+
const recordVersions = Array.from(
|
|
1203
|
+
new Set([
|
|
1204
|
+
rec.blender_versions.minimum,
|
|
1205
|
+
rec.blender_versions.doc_checked_version,
|
|
1206
|
+
...(rec.blender_versions.tested_or_targeted || []),
|
|
1207
|
+
...(rec.blender_versions.maintained_lts_versions || [])
|
|
1208
|
+
].filter(Boolean))
|
|
1209
|
+
);
|
|
1210
|
+
for (const ver of recordVersions) {
|
|
1211
|
+
byBlenderVersion[ver] = byBlenderVersion[ver] || [];
|
|
1212
|
+
if (!byBlenderVersion[ver].includes(rec.id)) {
|
|
1213
|
+
byBlenderVersion[ver].push(rec.id);
|
|
1214
|
+
}
|
|
1215
|
+
}
|
|
1216
|
+
|
|
1217
|
+
for (const sid of rec.related_ids.skill_ids) {
|
|
1218
|
+
bySkillId[sid] = bySkillId[sid] || { knowledge_ids: [], recipe_ids: [] };
|
|
1219
|
+
if (!bySkillId[sid].knowledge_ids.includes(rec.id)) {
|
|
1220
|
+
bySkillId[sid].knowledge_ids.push(rec.id);
|
|
1221
|
+
}
|
|
1222
|
+
}
|
|
1223
|
+
|
|
1224
|
+
for (const rid of rec.related_ids.recipe_ids) {
|
|
1225
|
+
byRecipeId[rid] = byRecipeId[rid] || { knowledge_ids: [], skill_ids: [] };
|
|
1226
|
+
if (!byRecipeId[rid].knowledge_ids.includes(rec.id)) {
|
|
1227
|
+
byRecipeId[rid].knowledge_ids.push(rec.id);
|
|
1228
|
+
}
|
|
1229
|
+
}
|
|
1230
|
+
|
|
1231
|
+
for (const sr of rec.source_refs) {
|
|
1232
|
+
bySourceId[sr.source_id] = bySourceId[sr.source_id] || { knowledge_ids: [], recipe_ids: [] };
|
|
1233
|
+
if (!bySourceId[sr.source_id].knowledge_ids.includes(rec.id)) {
|
|
1234
|
+
bySourceId[sr.source_id].knowledge_ids.push(rec.id);
|
|
1235
|
+
}
|
|
1236
|
+
}
|
|
1237
|
+
|
|
1238
|
+
// Complete field coverage across all record fields (Section 1.6)
|
|
1239
|
+
const applicabilityText = [
|
|
1240
|
+
...(rec.applicability?.when_to_apply || []),
|
|
1241
|
+
...(rec.applicability?.target_representations || []),
|
|
1242
|
+
...(rec.prerequisites || [])
|
|
1243
|
+
].join(' ');
|
|
1244
|
+
|
|
1245
|
+
const limitsAndExclusionsText = [
|
|
1246
|
+
...(rec.applicability?.when_not_to_apply || []),
|
|
1247
|
+
...(rec.known_limits || [])
|
|
1248
|
+
].join(' ');
|
|
1249
|
+
|
|
1250
|
+
const bodyText = [
|
|
1251
|
+
...(rec.aliases || []),
|
|
1252
|
+
...(rec.intent_signals || []),
|
|
1253
|
+
applicabilityText,
|
|
1254
|
+
limitsAndExclusionsText,
|
|
1255
|
+
...(rec.principles || []),
|
|
1256
|
+
...(rec.implementation_guidance?.workflow_steps || []),
|
|
1257
|
+
JSON.stringify(rec.implementation_guidance?.recommended_parameters || {}),
|
|
1258
|
+
rec.implementation_guidance?.blender_context || '',
|
|
1259
|
+
...(rec.observable_checks || []).map((c) => `${c.id} ${c.check} ${c.pass_condition} ${c.fail_indicator}`),
|
|
1260
|
+
...(rec.creative_affordances || []),
|
|
1261
|
+
...(rec.claims || []).map((c) => `${c.id} ${c.statement} ${c.scope} ${c.uncertainty_or_version_note || ''}`),
|
|
1262
|
+
rec.blender_versions?.minimum || '',
|
|
1263
|
+
(rec.blender_versions?.tested_or_targeted || []).join(' '),
|
|
1264
|
+
rec.blender_versions?.version_notes || ''
|
|
1265
|
+
].join(' ');
|
|
1266
|
+
|
|
1267
|
+
entries.push({
|
|
1268
|
+
id: rec.id,
|
|
1269
|
+
type: 'knowledge',
|
|
1270
|
+
title: rec.title,
|
|
1271
|
+
domain: rec.domain,
|
|
1272
|
+
kind: rec.kind,
|
|
1273
|
+
summary: rec.summary,
|
|
1274
|
+
evidence_status: rec.evidence_status,
|
|
1275
|
+
blender_minimum: rec.blender_versions.minimum,
|
|
1276
|
+
blender_versions: recordVersions,
|
|
1277
|
+
skill_ids: rec.related_ids.skill_ids,
|
|
1278
|
+
recipe_ids: rec.related_ids.recipe_ids,
|
|
1279
|
+
source_ids: rec.source_refs.map((s) => s.source_id),
|
|
1280
|
+
tokens: {
|
|
1281
|
+
id: tokenize(`${rec.id.replace(/^knowledge\./, '')} ${(rec.aliases || []).join(' ')}`),
|
|
1282
|
+
title: tokenize(`${rec.title} ${(rec.intent_signals || []).join(' ')}`),
|
|
1283
|
+
domain: tokenize(`${rec.domain} ${rec.kind}`),
|
|
1284
|
+
summary: tokenize(rec.summary),
|
|
1285
|
+
applicability: Array.from(new Set(tokenize(applicabilityText))),
|
|
1286
|
+
limits: Array.from(new Set(tokenize(limitsAndExclusionsText))),
|
|
1287
|
+
body: Array.from(new Set(tokenize(bodyText)))
|
|
1288
|
+
}
|
|
1289
|
+
});
|
|
1290
|
+
}
|
|
1291
|
+
|
|
1292
|
+
for (const recipe of recipesData.recipes) {
|
|
1293
|
+
const recipeDomains = [recipe.domain];
|
|
1294
|
+
for (const d of recipeDomains) {
|
|
1295
|
+
byDomain[d] = byDomain[d] || { knowledge_ids: [], recipe_ids: [] };
|
|
1296
|
+
if (!byDomain[d].recipe_ids.includes(recipe.id)) {
|
|
1297
|
+
byDomain[d].recipe_ids.push(recipe.id);
|
|
1298
|
+
}
|
|
1299
|
+
}
|
|
1300
|
+
|
|
1301
|
+
byEvidenceStatus[recipe.evidence_status] = byEvidenceStatus[recipe.evidence_status] || [];
|
|
1302
|
+
byEvidenceStatus[recipe.evidence_status].push(recipe.id);
|
|
1303
|
+
|
|
1304
|
+
const recipeVersions = Array.from(
|
|
1305
|
+
new Set([
|
|
1306
|
+
recipe.blender_versions.minimum,
|
|
1307
|
+
recipe.blender_versions.recommended,
|
|
1308
|
+
recipe.blender_versions.doc_checked_version,
|
|
1309
|
+
...(recipe.blender_versions.maintained_lts_versions || [])
|
|
1310
|
+
].filter(Boolean))
|
|
1311
|
+
);
|
|
1312
|
+
for (const ver of recipeVersions) {
|
|
1313
|
+
byBlenderVersion[ver] = byBlenderVersion[ver] || [];
|
|
1314
|
+
if (!byBlenderVersion[ver].includes(recipe.id)) {
|
|
1315
|
+
byBlenderVersion[ver].push(recipe.id);
|
|
1316
|
+
}
|
|
1317
|
+
}
|
|
1318
|
+
|
|
1319
|
+
const allSkills = Array.from(new Set(recipe.required_skill_ids || []));
|
|
1320
|
+
byRecipeId[recipe.id] = byRecipeId[recipe.id] || { knowledge_ids: [], skill_ids: [] };
|
|
1321
|
+
byRecipeId[recipe.id].skill_ids = allSkills;
|
|
1322
|
+
for (const kid of recipe.required_knowledge_ids || []) {
|
|
1323
|
+
if (!byRecipeId[recipe.id].knowledge_ids.includes(kid)) {
|
|
1324
|
+
byRecipeId[recipe.id].knowledge_ids.push(kid);
|
|
1325
|
+
}
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
for (const sid of allSkills) {
|
|
1329
|
+
bySkillId[sid] = bySkillId[sid] || { knowledge_ids: [], recipe_ids: [] };
|
|
1330
|
+
if (!bySkillId[sid].recipe_ids.includes(recipe.id)) {
|
|
1331
|
+
bySkillId[sid].recipe_ids.push(recipe.id);
|
|
1332
|
+
}
|
|
1333
|
+
}
|
|
1334
|
+
|
|
1335
|
+
for (const sr of recipe.source_refs) {
|
|
1336
|
+
bySourceId[sr.source_id] = bySourceId[sr.source_id] || { knowledge_ids: [], recipe_ids: [] };
|
|
1337
|
+
if (!bySourceId[sr.source_id].recipe_ids.includes(recipe.id)) {
|
|
1338
|
+
bySourceId[sr.source_id].recipe_ids.push(recipe.id);
|
|
1339
|
+
}
|
|
1340
|
+
}
|
|
1341
|
+
|
|
1342
|
+
const applicabilityText = [
|
|
1343
|
+
...(recipe.applicable_scenarios?.use_when || []),
|
|
1344
|
+
...(recipe.prerequisites || []),
|
|
1345
|
+
...(recipe.inputs || []).map((inp) => `${inp.name} ${inp.description}`)
|
|
1346
|
+
].join(' ');
|
|
1347
|
+
|
|
1348
|
+
const limitsAndExclusionsText = [
|
|
1349
|
+
...(recipe.applicable_scenarios?.do_not_use_when || []),
|
|
1350
|
+
...(recipe.failure_modes || []).map((f) => `${f.symptom} ${f.root_cause} ${f.recovery_action}`)
|
|
1351
|
+
].join(' ');
|
|
1352
|
+
|
|
1353
|
+
const bodyText = [
|
|
1354
|
+
recipe.intent,
|
|
1355
|
+
...(recipe.aliases || []),
|
|
1356
|
+
...(recipe.intent_signals || []),
|
|
1357
|
+
applicabilityText,
|
|
1358
|
+
limitsAndExclusionsText,
|
|
1359
|
+
...(recipe.stages || []).map((st) => `${st.id} ${st.title} ${st.objective} ${(st.actions || []).join(' ')} ${st.gate_check || ''}`),
|
|
1360
|
+
...(recipe.validation_criteria || []).map((vc) => `${vc.id} ${vc.criterion} ${vc.measurement_method} ${vc.pass_threshold}`),
|
|
1361
|
+
recipe.blender_versions?.version_considerations || '',
|
|
1362
|
+
recipe.documentation_path || ''
|
|
1363
|
+
].join(' ');
|
|
1364
|
+
|
|
1365
|
+
entries.push({
|
|
1366
|
+
id: recipe.id,
|
|
1367
|
+
type: 'recipe',
|
|
1368
|
+
title: recipe.title,
|
|
1369
|
+
domain: recipe.domain,
|
|
1370
|
+
domains: recipeDomains,
|
|
1371
|
+
kind: 'recipe-record',
|
|
1372
|
+
summary: recipe.summary,
|
|
1373
|
+
evidence_status: recipe.evidence_status,
|
|
1374
|
+
blender_minimum: recipe.blender_versions.minimum,
|
|
1375
|
+
blender_versions: recipeVersions,
|
|
1376
|
+
skill_ids: allSkills,
|
|
1377
|
+
knowledge_ids: recipe.required_knowledge_ids,
|
|
1378
|
+
source_ids: recipe.source_refs.map((s) => s.source_id),
|
|
1379
|
+
tokens: {
|
|
1380
|
+
id: tokenize(`${recipe.id.replace(/^recipe\./, '')} ${(recipe.aliases || []).join(' ')}`),
|
|
1381
|
+
title: tokenize(`${recipe.title} ${(recipe.intent_signals || []).join(' ')}`),
|
|
1382
|
+
domain: tokenize(recipe.domain),
|
|
1383
|
+
summary: tokenize(`${recipe.summary} ${recipe.intent}`),
|
|
1384
|
+
applicability: Array.from(new Set(tokenize(applicabilityText))),
|
|
1385
|
+
limits: Array.from(new Set(tokenize(limitsAndExclusionsText))),
|
|
1386
|
+
body: Array.from(new Set(tokenize(bodyText)))
|
|
1387
|
+
}
|
|
1388
|
+
});
|
|
1389
|
+
}
|
|
1390
|
+
|
|
1391
|
+
return {
|
|
1392
|
+
schema_version: '1.1.0',
|
|
1393
|
+
description: 'Deterministic bilingual (EN+VI) local lookup and field-weighted retrieval index for BlendOps knowledge records, recipes, sources, and skills.',
|
|
1394
|
+
retrieval_architecture: 'deterministic-bilingual-lexical-and-field-weighted-index',
|
|
1395
|
+
counts: {
|
|
1396
|
+
knowledge_records: knowledgeData.records.length,
|
|
1397
|
+
recipes: recipesData.recipes.length,
|
|
1398
|
+
sources: sourcesData.sources.length,
|
|
1399
|
+
domains: REQUIRED_DOMAINS.length,
|
|
1400
|
+
skills: skillsData.skills.length
|
|
1401
|
+
},
|
|
1402
|
+
by_domain: byDomain,
|
|
1403
|
+
by_kind: byKind,
|
|
1404
|
+
by_skill_id: bySkillId,
|
|
1405
|
+
by_recipe_id: byRecipeId,
|
|
1406
|
+
by_source_id: bySourceId,
|
|
1407
|
+
by_blender_version: byBlenderVersion,
|
|
1408
|
+
by_evidence_status: byEvidenceStatus,
|
|
1409
|
+
entries
|
|
1410
|
+
};
|
|
1411
|
+
}
|
|
1412
|
+
|
|
1413
|
+
export function renderKnowledgeAndRecipeCatalogMarkdown(rootDir = DEFAULT_ROOT) {
|
|
1414
|
+
const paths = resolveCatalogPaths(rootDir);
|
|
1415
|
+
const sourcesData = readJson(paths.sourcesPath);
|
|
1416
|
+
const knowledgeData = readJson(paths.knowledgePath);
|
|
1417
|
+
const recipesData = readJson(paths.recipesPath);
|
|
1418
|
+
|
|
1419
|
+
const lines = [
|
|
1420
|
+
'# BlendOps Knowledge & Recipe Catalog',
|
|
1421
|
+
'',
|
|
1422
|
+
'> Generated deterministically from `registry/knowledge-sources.json`, `registry/knowledge-catalog.json`, and `registry/recipe-catalog.json` via `npm run catalog:build`. Do not edit by hand.',
|
|
1423
|
+
'',
|
|
1424
|
+
'## Overview & Retrieval CLI',
|
|
1425
|
+
'',
|
|
1426
|
+
'BlendOps separates **atomic agent workflow skills** (`skills/*/SKILL.md`) from **reusable 3D/Blender domain knowledge** (`knowledge.*`) and **multi-stage construction recipes** (`recipe.*`).',
|
|
1427
|
+
'',
|
|
1428
|
+
'- **Deterministic Local Search (English & Vietnamese)**: `npx blendops catalog-search "<query>" [--type knowledge|recipe] [--domain <domain>]`',
|
|
1429
|
+
'- **Deterministic Record Resolution**: `npx blendops catalog-resolve <knowledge.id | recipe.id | source.id | skill-id>`',
|
|
1430
|
+
'- **Catalog Schema & Cross-Reference Validation**: `npx blendops catalog-validate`',
|
|
1431
|
+
'- **SceneSpec Validation & Plan Compilation**: `npx blendops scene-spec-validate <spec.json>` / `npx blendops plan-compile <spec.json>`',
|
|
1432
|
+
'',
|
|
1433
|
+
'| Metric | Count | Canonical Source |',
|
|
1434
|
+
'| :--- | ---: | :--- |',
|
|
1435
|
+
`| Knowledge Domains | ${REQUIRED_DOMAINS.length} | \`registry/knowledge-sources.json\` |`,
|
|
1436
|
+
`| Canonical Knowledge Records (\`knowledge.*\`) | ${knowledgeData.records.length} | \`registry/knowledge-catalog.json\` |`,
|
|
1437
|
+
`| Canonical Recipes (\`recipe.*\`) | ${recipesData.recipes.length} | \`registry/recipe-catalog.json\` |`,
|
|
1438
|
+
`| Authoritative Sources (\`source.*\`) | ${sourcesData.sources.length} | \`registry/knowledge-sources.json\` |`,
|
|
1439
|
+
`| Latest Stable Blender LTS Baseline | \`${sourcesData.taxonomy?.versionBaseline?.latest_stable_lts || '5.2.3 LTS'}\` | \`registry/knowledge-sources.json\` |`,
|
|
1440
|
+
'',
|
|
1441
|
+
'---',
|
|
1442
|
+
'',
|
|
1443
|
+
'## 1. Canonical Recipes (`recipe.*`)',
|
|
1444
|
+
'',
|
|
1445
|
+
'| Recipe ID | Title | Primary Domain | Stages | Required Skills | Linked Knowledge | Min Blender | Doc-Checked LTS | Evidence Status |',
|
|
1446
|
+
'| :--- | :--- | :--- | ---: | ---: | ---: | :--- | :--- | :--- |'
|
|
1447
|
+
];
|
|
1448
|
+
|
|
1449
|
+
for (const r of recipesData.recipes) {
|
|
1450
|
+
lines.push(
|
|
1451
|
+
`| \`${r.id}\` | ${r.title} | \`${r.domain}\` | ${r.stages.length} | ${r.required_skill_ids.length} | ${r.required_knowledge_ids.length} | \`${r.blender_versions.minimum}\` | \`${r.blender_versions.doc_checked_version}\` | \`${r.evidence_status}\` |`
|
|
1452
|
+
);
|
|
1453
|
+
}
|
|
1454
|
+
|
|
1455
|
+
lines.push(
|
|
1456
|
+
'',
|
|
1457
|
+
'### Recipe Details & Scenario Linkages',
|
|
1458
|
+
''
|
|
1459
|
+
);
|
|
1460
|
+
|
|
1461
|
+
for (const r of recipesData.recipes) {
|
|
1462
|
+
lines.push(
|
|
1463
|
+
`#### \`${r.id}\` — ${r.title}`,
|
|
1464
|
+
'',
|
|
1465
|
+
`- **Intent**: ${r.intent}`,
|
|
1466
|
+
`- **Domain**: \`${r.domain}\``,
|
|
1467
|
+
`- **Required Skills**: ${r.required_skill_ids.map((s) => `\`${s}\``).join(', ')}`,
|
|
1468
|
+
`- **Knowledge Records**: ${r.required_knowledge_ids.map((k) => `\`${k}\``).join(', ')}`,
|
|
1469
|
+
`- **Stages**: ${r.stages.map((st) => `\`${st.id}\` (Stage ${st.stage_number})`).join(' → ')}`
|
|
1470
|
+
);
|
|
1471
|
+
if (r.documentation_path) {
|
|
1472
|
+
lines.push(`- **Scenario Reference Doc**: \`${r.documentation_path}\``);
|
|
1473
|
+
}
|
|
1474
|
+
lines.push('');
|
|
1475
|
+
}
|
|
1476
|
+
|
|
1477
|
+
lines.push(
|
|
1478
|
+
'---',
|
|
1479
|
+
'',
|
|
1480
|
+
'## 2. Canonical Knowledge Records by Domain (`knowledge.*`)',
|
|
1481
|
+
''
|
|
1482
|
+
);
|
|
1483
|
+
|
|
1484
|
+
for (const domainId of REQUIRED_DOMAINS) {
|
|
1485
|
+
const domRecords = knowledgeData.records.filter((k) => k.domain === domainId);
|
|
1486
|
+
lines.push(
|
|
1487
|
+
`### Domain: \`${domainId}\` (${domRecords.length} records)`,
|
|
1488
|
+
'',
|
|
1489
|
+
'| Knowledge ID | Title | Kind | Min Blender | Doc-Checked LTS | Evidence Status | Linked Skills | Linked Recipes |',
|
|
1490
|
+
'| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |'
|
|
1491
|
+
);
|
|
1492
|
+
for (const rec of domRecords) {
|
|
1493
|
+
lines.push(
|
|
1494
|
+
`| \`${rec.id}\` | ${rec.title} | \`${rec.kind}\` | \`${rec.blender_versions.minimum}\` | \`${rec.blender_versions.doc_checked_version}\` | \`${rec.evidence_status}\` | ${rec.related_ids.skill_ids.map((s) => `\`${s}\``).join(', ')} | ${rec.related_ids.recipe_ids.map((r) => `\`${r}\``).join(', ')} |`
|
|
1495
|
+
);
|
|
1496
|
+
}
|
|
1497
|
+
lines.push('');
|
|
1498
|
+
}
|
|
1499
|
+
|
|
1500
|
+
lines.push(
|
|
1501
|
+
'---',
|
|
1502
|
+
'',
|
|
1503
|
+
'## 3. Authoritative Source Registry (`source.*`)',
|
|
1504
|
+
'',
|
|
1505
|
+
'| Source ID | Title | Authority | Publisher | Locator / Section | Verified Date | License / Usage |',
|
|
1506
|
+
'| :--- | :--- | :--- | :--- | :--- | :--- | :--- |'
|
|
1507
|
+
);
|
|
1508
|
+
|
|
1509
|
+
for (const src of sourcesData.sources) {
|
|
1510
|
+
lines.push(
|
|
1511
|
+
`| \`${src.id}\` | ${src.title} | \`${src.authority}\` | ${src.publisher} | ${src.locator_or_section} | \`${src.verification_date}\` | ${src.license_note} |`
|
|
1512
|
+
);
|
|
1513
|
+
}
|
|
1514
|
+
|
|
1515
|
+
lines.push('');
|
|
1516
|
+
return lines.join('\n');
|
|
1517
|
+
}
|
|
1518
|
+
|
|
1519
|
+
export function searchCatalog(rootDir = DEFAULT_ROOT, query = '', options = {}) {
|
|
1520
|
+
const paths = resolveCatalogPaths(rootDir);
|
|
1521
|
+
const indexData = fs.existsSync(paths.indexPath)
|
|
1522
|
+
? readJson(paths.indexPath)
|
|
1523
|
+
: generateCatalogIndexData(rootDir);
|
|
1524
|
+
|
|
1525
|
+
const foldedRawQuery = foldVietnameseDiacritics(query);
|
|
1526
|
+
const rawSimpleTokens = foldedRawQuery
|
|
1527
|
+
.replace(/[^a-z0-9+#.-]+/g, ' ')
|
|
1528
|
+
.split(/\s+/)
|
|
1529
|
+
.map((t) => t.replace(/^[.-]+|[.-]+$/g, ''))
|
|
1530
|
+
.filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
|
|
1531
|
+
|
|
1532
|
+
const queryTokens = tokenize(query);
|
|
1533
|
+
const queryLang = detectQueryLanguage(query);
|
|
1534
|
+
const typeFilter = options.type && options.type !== 'all' ? options.type : null;
|
|
1535
|
+
const domainFilter = options.domain || null;
|
|
1536
|
+
const kindFilter = options.kind || null;
|
|
1537
|
+
const skillFilter = options.skill_id || null;
|
|
1538
|
+
const versionFilter = options.blender_version || null;
|
|
1539
|
+
const evidenceFilter = options.evidence_status || null;
|
|
1540
|
+
const limit = Number(options.limit) > 0 ? Number(options.limit) : 10;
|
|
1541
|
+
|
|
1542
|
+
// Detect out-of-scope DCC / game engine / non-3D tokens and phrases
|
|
1543
|
+
const outOfScopeHits = rawSimpleTokens.filter((t) => OUT_OF_SCOPE_TOKENS.has(t));
|
|
1544
|
+
for (const phrase of OUT_OF_SCOPE_PHRASES) {
|
|
1545
|
+
if (foldedRawQuery.includes(phrase) && !outOfScopeHits.includes(phrase)) {
|
|
1546
|
+
outOfScopeHits.push(phrase);
|
|
1547
|
+
}
|
|
1548
|
+
}
|
|
1549
|
+
|
|
1550
|
+
// Detect whether query explicitly asks about limitations, exclusions, or "when not to use"
|
|
1551
|
+
const isLimitationOrExclusionQuery = /\b(limit|limits|limitation|limitations|when not|do not use|avoid|unsupported|cannot|khong dung|han che|gioi han|khi nao khong)\b/i.test(foldedRawQuery);
|
|
1552
|
+
|
|
1553
|
+
const candidates = indexData.entries.filter((entry) => {
|
|
1554
|
+
if (typeFilter && entry.type !== typeFilter) return false;
|
|
1555
|
+
if (domainFilter && entry.domain !== domainFilter) return false;
|
|
1556
|
+
if (kindFilter && entry.kind !== kindFilter) return false;
|
|
1557
|
+
if (skillFilter && !(entry.skill_ids || []).includes(skillFilter)) return false;
|
|
1558
|
+
if (versionFilter) {
|
|
1559
|
+
const parseVer = (s) => {
|
|
1560
|
+
const m = String(s || '').match(/(\d+)\.(\d+)/);
|
|
1561
|
+
return m ? Number(m[1]) * 100 + Number(m[2]) : null;
|
|
1562
|
+
};
|
|
1563
|
+
const reqVer = parseVer(versionFilter);
|
|
1564
|
+
const minVer = parseVer(entry.blender_minimum);
|
|
1565
|
+
const normFilter = String(versionFilter).replace(/\+$/, '').trim().toLowerCase();
|
|
1566
|
+
const versionMatched =
|
|
1567
|
+
(entry.blender_versions || []).some((v) => {
|
|
1568
|
+
const normV = String(v).replace(/\+$/, '').trim().toLowerCase();
|
|
1569
|
+
return normV === normFilter || normV.startsWith(normFilter) || normFilter.startsWith(normV);
|
|
1570
|
+
}) ||
|
|
1571
|
+
(reqVer !== null && minVer !== null && minVer <= reqVer);
|
|
1572
|
+
if (!versionMatched) return false;
|
|
1573
|
+
}
|
|
1574
|
+
if (evidenceFilter && entry.evidence_status !== evidenceFilter) return false;
|
|
1575
|
+
return true;
|
|
1576
|
+
});
|
|
1577
|
+
|
|
1578
|
+
if (queryTokens.length === 0) {
|
|
1579
|
+
return {
|
|
1580
|
+
query,
|
|
1581
|
+
language: queryLang,
|
|
1582
|
+
retrieval_method: 'deterministic-bilingual-lexical-and-field-weighted-index',
|
|
1583
|
+
status: candidates.length > 0 ? 'matched' : 'no_relevant_match',
|
|
1584
|
+
coverage_gap: candidates.length === 0,
|
|
1585
|
+
total_matches: candidates.length,
|
|
1586
|
+
results: candidates.slice(0, limit).map((c) => ({
|
|
1587
|
+
id: c.id,
|
|
1588
|
+
type: c.type,
|
|
1589
|
+
title: c.title,
|
|
1590
|
+
domain: c.domain,
|
|
1591
|
+
kind: c.kind,
|
|
1592
|
+
summary: c.summary,
|
|
1593
|
+
evidence_status: c.evidence_status,
|
|
1594
|
+
blender_minimum: c.blender_minimum,
|
|
1595
|
+
minimum_blender: c.blender_minimum,
|
|
1596
|
+
score: 1.0,
|
|
1597
|
+
matched_tokens: [],
|
|
1598
|
+
matched_fields: ['filter']
|
|
1599
|
+
}))
|
|
1600
|
+
};
|
|
1601
|
+
}
|
|
1602
|
+
|
|
1603
|
+
const scored = [];
|
|
1604
|
+
for (const entry of candidates) {
|
|
1605
|
+
let score = 0;
|
|
1606
|
+
const matchedTokens = [];
|
|
1607
|
+
const matchedFields = new Set();
|
|
1608
|
+
|
|
1609
|
+
const idSet = new Set(entry.tokens.id || []);
|
|
1610
|
+
const titleSet = new Set(entry.tokens.title || []);
|
|
1611
|
+
const domainSet = new Set(entry.tokens.domain || []);
|
|
1612
|
+
const summarySet = new Set(entry.tokens.summary || []);
|
|
1613
|
+
const appSet = new Set(entry.tokens.applicability || []);
|
|
1614
|
+
const limitsSet = new Set(entry.tokens.limits || []);
|
|
1615
|
+
const bodySet = new Set(entry.tokens.body || []);
|
|
1616
|
+
|
|
1617
|
+
for (const qToken of queryTokens) {
|
|
1618
|
+
let tokenMatched = false;
|
|
1619
|
+
if (idSet.has(qToken)) {
|
|
1620
|
+
score += 5.0;
|
|
1621
|
+
matchedFields.add('id');
|
|
1622
|
+
tokenMatched = true;
|
|
1623
|
+
}
|
|
1624
|
+
if (titleSet.has(qToken)) {
|
|
1625
|
+
score += 4.0;
|
|
1626
|
+
matchedFields.add('title');
|
|
1627
|
+
tokenMatched = true;
|
|
1628
|
+
}
|
|
1629
|
+
if (domainSet.has(qToken)) {
|
|
1630
|
+
score += 2.5;
|
|
1631
|
+
matchedFields.add('domain');
|
|
1632
|
+
tokenMatched = true;
|
|
1633
|
+
}
|
|
1634
|
+
if (summarySet.has(qToken)) {
|
|
1635
|
+
score += 2.5;
|
|
1636
|
+
matchedFields.add('summary');
|
|
1637
|
+
tokenMatched = true;
|
|
1638
|
+
}
|
|
1639
|
+
if (limitsSet.has(qToken) && isLimitationOrExclusionQuery) {
|
|
1640
|
+
score += 2.25;
|
|
1641
|
+
matchedFields.add('limits');
|
|
1642
|
+
tokenMatched = true;
|
|
1643
|
+
} else if (appSet.has(qToken)) {
|
|
1644
|
+
score += 1.5;
|
|
1645
|
+
matchedFields.add('applicability');
|
|
1646
|
+
tokenMatched = true;
|
|
1647
|
+
} else if (limitsSet.has(qToken)) {
|
|
1648
|
+
score += 1.25;
|
|
1649
|
+
matchedFields.add('limits');
|
|
1650
|
+
tokenMatched = true;
|
|
1651
|
+
} else if (bodySet.has(qToken)) {
|
|
1652
|
+
score += 1.5;
|
|
1653
|
+
matchedFields.add('body');
|
|
1654
|
+
tokenMatched = true;
|
|
1655
|
+
}
|
|
1656
|
+
|
|
1657
|
+
if (!tokenMatched && qToken.length >= 4) {
|
|
1658
|
+
const prefixHitIdOrTitle = [...idSet, ...titleSet].some(
|
|
1659
|
+
(t) => t.startsWith(qToken) || qToken.startsWith(t)
|
|
1660
|
+
);
|
|
1661
|
+
const prefixHitSummaryOrBody = [...summarySet, ...bodySet].some(
|
|
1662
|
+
(t) => t.length >= 4 && (t.startsWith(qToken) || qToken.startsWith(t))
|
|
1663
|
+
);
|
|
1664
|
+
if (prefixHitIdOrTitle) {
|
|
1665
|
+
score += 2.5;
|
|
1666
|
+
matchedFields.add('title_prefix');
|
|
1667
|
+
tokenMatched = true;
|
|
1668
|
+
} else if (prefixHitSummaryOrBody) {
|
|
1669
|
+
score += 1.0;
|
|
1670
|
+
matchedFields.add('body_prefix');
|
|
1671
|
+
tokenMatched = true;
|
|
1672
|
+
}
|
|
1673
|
+
}
|
|
1674
|
+
|
|
1675
|
+
if (tokenMatched) {
|
|
1676
|
+
matchedTokens.push(qToken);
|
|
1677
|
+
}
|
|
1678
|
+
}
|
|
1679
|
+
|
|
1680
|
+
if (matchedTokens.length > 0) {
|
|
1681
|
+
const coverageRatio = matchedTokens.length / queryTokens.length;
|
|
1682
|
+
score = Number((score * (0.6 + 0.4 * coverageRatio)).toFixed(3));
|
|
1683
|
+
scored.push({
|
|
1684
|
+
id: entry.id,
|
|
1685
|
+
type: entry.type,
|
|
1686
|
+
title: entry.title,
|
|
1687
|
+
domain: entry.domain,
|
|
1688
|
+
kind: entry.kind,
|
|
1689
|
+
summary: entry.summary,
|
|
1690
|
+
evidence_status: entry.evidence_status,
|
|
1691
|
+
blender_minimum: entry.blender_minimum,
|
|
1692
|
+
minimum_blender: entry.blender_minimum,
|
|
1693
|
+
score,
|
|
1694
|
+
matched_tokens: matchedTokens,
|
|
1695
|
+
matched_fields: Array.from(matchedFields)
|
|
1696
|
+
});
|
|
1697
|
+
}
|
|
1698
|
+
}
|
|
1699
|
+
|
|
1700
|
+
scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
|
|
1701
|
+
|
|
1702
|
+
const topScore = scored[0]?.score || 0;
|
|
1703
|
+
const topCoverage = queryTokens.length > 0 ? (scored[0]?.matched_tokens.length || 0) / queryTokens.length : 1;
|
|
1704
|
+
const hasExplicitBlenderAnchor = /\b(blender|gltf|glb|cycles|eevee|agx|geometry nodes|principled bsdf)\b/i.test(foldedRawQuery);
|
|
1705
|
+
|
|
1706
|
+
if (
|
|
1707
|
+
scored.length === 0 ||
|
|
1708
|
+
(outOfScopeHits.length >= 1 && !hasExplicitBlenderAnchor && topCoverage < 0.5) ||
|
|
1709
|
+
(outOfScopeHits.length >= 2 && topCoverage < 0.45) ||
|
|
1710
|
+
(queryTokens.length >= 3 && topScore < 3.0)
|
|
1711
|
+
) {
|
|
1712
|
+
return {
|
|
1713
|
+
query,
|
|
1714
|
+
language: queryLang,
|
|
1715
|
+
retrieval_method: 'deterministic-bilingual-lexical-and-field-weighted-index',
|
|
1716
|
+
status: 'no_relevant_match',
|
|
1717
|
+
coverage_gap: true,
|
|
1718
|
+
total_matches: 0,
|
|
1719
|
+
coverage_gap_reason:
|
|
1720
|
+
outOfScopeHits.length > 0
|
|
1721
|
+
? `Query references out-of-scope DCC/engine tools (${outOfScopeHits.join(', ')}) not covered by BlendOps Blender/glTF catalogs.`
|
|
1722
|
+
: 'No knowledge or recipe record met the deterministic relevance threshold.',
|
|
1723
|
+
results: []
|
|
1724
|
+
};
|
|
1725
|
+
}
|
|
1726
|
+
|
|
1727
|
+
return {
|
|
1728
|
+
query,
|
|
1729
|
+
language: queryLang,
|
|
1730
|
+
retrieval_method: 'deterministic-bilingual-lexical-and-field-weighted-index',
|
|
1731
|
+
status: 'matched',
|
|
1732
|
+
coverage_gap: false,
|
|
1733
|
+
total_matches: scored.length,
|
|
1734
|
+
results: scored.slice(0, limit)
|
|
1735
|
+
};
|
|
1736
|
+
}
|
|
1737
|
+
|
|
1738
|
+
export function resolveCatalogRecord(rootDir = DEFAULT_ROOT, recordId = '') {
|
|
1739
|
+
const paths = resolveCatalogPaths(rootDir);
|
|
1740
|
+
const sourcesData = readJson(paths.sourcesPath);
|
|
1741
|
+
const knowledgeData = readJson(paths.knowledgePath);
|
|
1742
|
+
const recipesData = readJson(paths.recipesPath);
|
|
1743
|
+
const skillsData = readJson(paths.skillsPath);
|
|
1744
|
+
|
|
1745
|
+
const sourceMap = new Map(sourcesData.sources.map((s) => [s.id, s]));
|
|
1746
|
+
const knowledgeMap = new Map(knowledgeData.records.map((k) => [k.id, k]));
|
|
1747
|
+
const recipeMap = new Map(recipesData.recipes.map((r) => [r.id, r]));
|
|
1748
|
+
const skillMap = new Map(skillsData.skills.map((s) => [s.id, s]));
|
|
1749
|
+
|
|
1750
|
+
if (knowledgeMap.has(recordId)) {
|
|
1751
|
+
const record = knowledgeMap.get(recordId);
|
|
1752
|
+
return {
|
|
1753
|
+
found: true,
|
|
1754
|
+
id: record.id,
|
|
1755
|
+
type: 'knowledge',
|
|
1756
|
+
record,
|
|
1757
|
+
resolved_links: {
|
|
1758
|
+
sources: (record.source_refs || []).map((sr) => ({
|
|
1759
|
+
...sr,
|
|
1760
|
+
source: sourceMap.get(sr.source_id) || null
|
|
1761
|
+
})),
|
|
1762
|
+
related_knowledge: (record.related_ids?.knowledge_ids || []).map((id) => {
|
|
1763
|
+
const k = knowledgeMap.get(id);
|
|
1764
|
+
return k ? { id: k.id, title: k.title, domain: k.domain, kind: k.kind } : { id, missing: true };
|
|
1765
|
+
}),
|
|
1766
|
+
related_recipes: (record.related_ids?.recipe_ids || []).map((id) => {
|
|
1767
|
+
const r = recipeMap.get(id);
|
|
1768
|
+
return r ? { id: r.id, title: r.title, domain: r.domain } : { id, missing: true };
|
|
1769
|
+
}),
|
|
1770
|
+
related_skills: (record.related_ids?.skill_ids || []).map((id) => {
|
|
1771
|
+
const s = skillMap.get(id);
|
|
1772
|
+
return s
|
|
1773
|
+
? {
|
|
1774
|
+
id: s.id,
|
|
1775
|
+
display_name: s.display_name || s.name || s.id,
|
|
1776
|
+
workflow_stage: s.workflow_stage || deriveSkillWorkflowStage(s),
|
|
1777
|
+
capability_tier: s.capabilityTier || s.capability_tier || 'L0'
|
|
1778
|
+
}
|
|
1779
|
+
: { id, missing: true };
|
|
1780
|
+
})
|
|
1781
|
+
}
|
|
1782
|
+
};
|
|
1783
|
+
}
|
|
1784
|
+
|
|
1785
|
+
if (recipeMap.has(recordId)) {
|
|
1786
|
+
const record = recipeMap.get(recordId);
|
|
1787
|
+
return {
|
|
1788
|
+
found: true,
|
|
1789
|
+
id: record.id,
|
|
1790
|
+
type: 'recipe',
|
|
1791
|
+
record,
|
|
1792
|
+
resolved_links: {
|
|
1793
|
+
sources: (record.source_refs || []).map((sr) => ({
|
|
1794
|
+
...sr,
|
|
1795
|
+
source: sourceMap.get(sr.source_id) || null
|
|
1796
|
+
})),
|
|
1797
|
+
knowledge_records: (record.required_knowledge_ids || []).map((id) => {
|
|
1798
|
+
const k = knowledgeMap.get(id);
|
|
1799
|
+
return k ? { id: k.id, title: k.title, domain: k.domain, kind: k.kind } : { id, missing: true };
|
|
1800
|
+
}),
|
|
1801
|
+
required_skills: (record.required_skill_ids || []).map((id) => {
|
|
1802
|
+
const s = skillMap.get(id);
|
|
1803
|
+
return s
|
|
1804
|
+
? {
|
|
1805
|
+
id: s.id,
|
|
1806
|
+
display_name: s.display_name || s.name || s.id,
|
|
1807
|
+
workflow_stage: s.workflow_stage || deriveSkillWorkflowStage(s),
|
|
1808
|
+
capability_tier: s.capabilityTier || s.capability_tier || 'L0'
|
|
1809
|
+
}
|
|
1810
|
+
: { id, missing: true };
|
|
1811
|
+
})
|
|
1812
|
+
}
|
|
1813
|
+
};
|
|
1814
|
+
}
|
|
1815
|
+
|
|
1816
|
+
if (sourceMap.has(recordId)) {
|
|
1817
|
+
const record = sourceMap.get(recordId);
|
|
1818
|
+
const linkedKnowledge = knowledgeData.records
|
|
1819
|
+
.filter((k) => (k.source_refs || []).some((sr) => sr.source_id === recordId))
|
|
1820
|
+
.map((k) => ({ id: k.id, title: k.title, domain: k.domain }));
|
|
1821
|
+
const linkedRecipes = recipesData.recipes
|
|
1822
|
+
.filter((r) => (r.source_refs || []).some((sr) => sr.source_id === recordId))
|
|
1823
|
+
.map((r) => ({ id: r.id, title: r.title, category: r.domain }));
|
|
1824
|
+
return {
|
|
1825
|
+
found: true,
|
|
1826
|
+
id: record.id,
|
|
1827
|
+
type: 'source',
|
|
1828
|
+
record,
|
|
1829
|
+
resolved_links: {
|
|
1830
|
+
knowledge_records: linkedKnowledge,
|
|
1831
|
+
recipes: linkedRecipes
|
|
1832
|
+
}
|
|
1833
|
+
};
|
|
1834
|
+
}
|
|
1835
|
+
|
|
1836
|
+
if (skillMap.has(recordId)) {
|
|
1837
|
+
const record = skillMap.get(recordId);
|
|
1838
|
+
const linkedKnowledge = knowledgeData.records
|
|
1839
|
+
.filter((k) => (k.related_ids?.skill_ids || []).includes(recordId))
|
|
1840
|
+
.map((k) => ({ id: k.id, title: k.title, domain: k.domain, kind: k.kind }));
|
|
1841
|
+
const linkedRecipes = recipesData.recipes
|
|
1842
|
+
.filter((r) => (r.required_skill_ids || []).includes(recordId))
|
|
1843
|
+
.map((r) => ({ id: r.id, title: r.title, domain: r.domain }));
|
|
1844
|
+
return {
|
|
1845
|
+
found: true,
|
|
1846
|
+
id: record.id,
|
|
1847
|
+
type: 'skill',
|
|
1848
|
+
record,
|
|
1849
|
+
resolved_links: {
|
|
1850
|
+
knowledge_records: linkedKnowledge,
|
|
1851
|
+
recipes: linkedRecipes
|
|
1852
|
+
}
|
|
1853
|
+
};
|
|
1854
|
+
}
|
|
1855
|
+
|
|
1856
|
+
return {
|
|
1857
|
+
found: false,
|
|
1858
|
+
id: recordId,
|
|
1859
|
+
error: `Unknown catalog ID "${recordId}". Expected knowledge.<slug>, recipe.<slug>, source.<slug>, or a canonical skill ID.`
|
|
1860
|
+
};
|
|
1861
|
+
}
|
|
1862
|
+
|
|
1863
|
+
/**
|
|
1864
|
+
* Computes retrieval metrics (Recall@k, Standard Precision@k, Target-Normalized Precision@k, MRR)
|
|
1865
|
+
* for a single query result list against expected top IDs.
|
|
1866
|
+
*
|
|
1867
|
+
* - Deduplicates both `results` (preserving rank order) and `expectedTopIds` so duplicate returned IDs
|
|
1868
|
+
* or duplicate expected IDs can never inflate Precision@k or Recall@k.
|
|
1869
|
+
* - `standard_precision_at_k` divides strictly by `k` (never `topSlice.length`), preventing short
|
|
1870
|
+
* result lists from inflating Precision@k.
|
|
1871
|
+
* - `target_precision_at_k` divides by `min(k, |expectedUnique|)` (never `topSlice.length`),
|
|
1872
|
+
* preventing short result lists from inflating target-normalized precision.
|
|
1873
|
+
*/
|
|
1874
|
+
export function computeRetrievalMetricsForCase(results = [], expectedTopIds = [], kInput = 3) {
|
|
1875
|
+
const k = Math.max(1, Math.floor(Number(kInput) || 3));
|
|
1876
|
+
|
|
1877
|
+
const seenResultIds = new Set();
|
|
1878
|
+
const uniqueResults = [];
|
|
1879
|
+
for (const r of Array.isArray(results) ? results : []) {
|
|
1880
|
+
const id = typeof r === 'string' ? r : r?.id;
|
|
1881
|
+
if (!id || seenResultIds.has(id)) continue;
|
|
1882
|
+
seenResultIds.add(id);
|
|
1883
|
+
uniqueResults.push(typeof r === 'string' ? { id } : r);
|
|
1884
|
+
}
|
|
1885
|
+
|
|
1886
|
+
const seenExpectedIds = new Set();
|
|
1887
|
+
const expectedUnique = [];
|
|
1888
|
+
for (const expId of Array.isArray(expectedTopIds) ? expectedTopIds : []) {
|
|
1889
|
+
if (!expId || seenExpectedIds.has(expId)) continue;
|
|
1890
|
+
seenExpectedIds.add(expId);
|
|
1891
|
+
expectedUnique.push(expId);
|
|
1892
|
+
}
|
|
1893
|
+
|
|
1894
|
+
const topSlice = uniqueResults.slice(0, k).map((r) => r.id);
|
|
1895
|
+
const matchedExpected = expectedUnique.filter((expId) => topSlice.includes(expId));
|
|
1896
|
+
const missingExpected = expectedUnique.filter((expId) => !topSlice.includes(expId));
|
|
1897
|
+
|
|
1898
|
+
const recallAtK =
|
|
1899
|
+
expectedUnique.length > 0 ? matchedExpected.length / expectedUnique.length : 1;
|
|
1900
|
+
const standardPrecisionAtK = matchedExpected.length / k;
|
|
1901
|
+
const targetDenominator =
|
|
1902
|
+
expectedUnique.length > 0 ? Math.min(k, expectedUnique.length) : k;
|
|
1903
|
+
const targetPrecisionAtK = matchedExpected.length / targetDenominator;
|
|
1904
|
+
|
|
1905
|
+
let firstRank = 0;
|
|
1906
|
+
for (let idx = 0; idx < uniqueResults.length; idx += 1) {
|
|
1907
|
+
if (seenExpectedIds.has(uniqueResults[idx].id)) {
|
|
1908
|
+
firstRank = idx + 1;
|
|
1909
|
+
break;
|
|
1910
|
+
}
|
|
1911
|
+
}
|
|
1912
|
+
const reciprocalRank = firstRank > 0 ? 1 / firstRank : 0;
|
|
1913
|
+
|
|
1914
|
+
return {
|
|
1915
|
+
k,
|
|
1916
|
+
top_slice: topSlice,
|
|
1917
|
+
expected_unique: expectedUnique,
|
|
1918
|
+
matched_expected: matchedExpected,
|
|
1919
|
+
missing_expected: missingExpected,
|
|
1920
|
+
duplicate_result_ids_removed: (Array.isArray(results) ? results.length : 0) - uniqueResults.length,
|
|
1921
|
+
recall_at_k: Number(recallAtK.toFixed(4)),
|
|
1922
|
+
standard_precision_at_k: Number(standardPrecisionAtK.toFixed(4)),
|
|
1923
|
+
target_precision_at_k: Number(targetPrecisionAtK.toFixed(4)),
|
|
1924
|
+
reciprocal_rank: Number(reciprocalRank.toFixed(4)),
|
|
1925
|
+
first_rank: firstRank,
|
|
1926
|
+
};
|
|
1927
|
+
}
|
|
1928
|
+
|
|
1929
|
+
export function runCatalogRetrievalEvals(rootDir = DEFAULT_ROOT) {
|
|
1930
|
+
const evalsPath = path.join(rootDir, 'evals/catalog-retrieval-evals.json');
|
|
1931
|
+
if (!fs.existsSync(evalsPath)) {
|
|
1932
|
+
return {
|
|
1933
|
+
passed: false,
|
|
1934
|
+
total: 0,
|
|
1935
|
+
passed_count: 0,
|
|
1936
|
+
failures: [`Missing evaluation suite: ${evalsPath}`]
|
|
1937
|
+
};
|
|
1938
|
+
}
|
|
1939
|
+
const suite = readJson(evalsPath);
|
|
1940
|
+
const failures = [];
|
|
1941
|
+
let passedCount = 0;
|
|
1942
|
+
|
|
1943
|
+
let positiveCasesCount = 0;
|
|
1944
|
+
let recallSum = 0;
|
|
1945
|
+
let targetPrecisionSum = 0;
|
|
1946
|
+
let standardPrecisionSum = 0;
|
|
1947
|
+
let reciprocalRankSum = 0;
|
|
1948
|
+
|
|
1949
|
+
let noMatchCasesCount = 0;
|
|
1950
|
+
let noMatchCorrectCount = 0;
|
|
1951
|
+
let unsupportedFalsePositives = 0;
|
|
1952
|
+
|
|
1953
|
+
const langCounts = {
|
|
1954
|
+
en: { total: 0, passed: 0 },
|
|
1955
|
+
vi: { total: 0, passed: 0 },
|
|
1956
|
+
mixed_vi_en: { total: 0, passed: 0 }
|
|
1957
|
+
};
|
|
1958
|
+
|
|
1959
|
+
for (const testCase of suite.cases || []) {
|
|
1960
|
+
const response = searchCatalog(rootDir, testCase.query, testCase.filters || {});
|
|
1961
|
+
const langKey = testCase.language || detectQueryLanguage(testCase.query);
|
|
1962
|
+
if (!langCounts[langKey]) {
|
|
1963
|
+
langCounts[langKey] = { total: 0, passed: 0 };
|
|
1964
|
+
}
|
|
1965
|
+
langCounts[langKey].total += 1;
|
|
1966
|
+
|
|
1967
|
+
if (testCase.expect_no_match) {
|
|
1968
|
+
noMatchCasesCount += 1;
|
|
1969
|
+
if (response.status === 'no_relevant_match' && response.coverage_gap === true && response.results.length === 0) {
|
|
1970
|
+
passedCount += 1;
|
|
1971
|
+
noMatchCorrectCount += 1;
|
|
1972
|
+
langCounts[langKey].passed += 1;
|
|
1973
|
+
} else {
|
|
1974
|
+
unsupportedFalsePositives += 1;
|
|
1975
|
+
failures.push(
|
|
1976
|
+
`Case ${testCase.id}: expected no_relevant_match / coverage_gap=true, got status=${response.status} with top result ${response.results[0]?.id || 'none'}`
|
|
1977
|
+
);
|
|
1978
|
+
}
|
|
1979
|
+
continue;
|
|
1980
|
+
}
|
|
1981
|
+
|
|
1982
|
+
positiveCasesCount += 1;
|
|
1983
|
+
|
|
1984
|
+
if (response.status !== 'matched' || response.results.length === 0) {
|
|
1985
|
+
failures.push(`Case ${testCase.id}: expected match for "${testCase.query}", got status=${response.status}`);
|
|
1986
|
+
continue;
|
|
1987
|
+
}
|
|
1988
|
+
|
|
1989
|
+
const k = testCase.max_rank || 3;
|
|
1990
|
+
const caseMetrics = computeRetrievalMetricsForCase(
|
|
1991
|
+
response.results,
|
|
1992
|
+
testCase.expected_top_ids || [],
|
|
1993
|
+
k
|
|
1994
|
+
);
|
|
1995
|
+
|
|
1996
|
+
recallSum += caseMetrics.recall_at_k;
|
|
1997
|
+
targetPrecisionSum += caseMetrics.target_precision_at_k;
|
|
1998
|
+
standardPrecisionSum += caseMetrics.standard_precision_at_k;
|
|
1999
|
+
reciprocalRankSum += caseMetrics.reciprocal_rank;
|
|
2000
|
+
|
|
2001
|
+
if (caseMetrics.missing_expected.length > 0) {
|
|
2002
|
+
failures.push(
|
|
2003
|
+
`Case ${testCase.id}: expected [${caseMetrics.expected_unique.join(', ')}] within top ${k}, got [${caseMetrics.top_slice.join(', ')}]`
|
|
2004
|
+
);
|
|
2005
|
+
} else {
|
|
2006
|
+
passedCount += 1;
|
|
2007
|
+
langCounts[langKey].passed += 1;
|
|
2008
|
+
}
|
|
2009
|
+
}
|
|
2010
|
+
|
|
2011
|
+
const metrics = {
|
|
2012
|
+
recall_at_k: positiveCasesCount > 0 ? Number((recallSum / positiveCasesCount).toFixed(4)) : 1,
|
|
2013
|
+
precision_at_k:
|
|
2014
|
+
positiveCasesCount > 0 ? Number((targetPrecisionSum / positiveCasesCount).toFixed(4)) : 1,
|
|
2015
|
+
standard_precision_at_k:
|
|
2016
|
+
positiveCasesCount > 0 ? Number((standardPrecisionSum / positiveCasesCount).toFixed(4)) : 1,
|
|
2017
|
+
target_precision_at_k:
|
|
2018
|
+
positiveCasesCount > 0 ? Number((targetPrecisionSum / positiveCasesCount).toFixed(4)) : 1,
|
|
2019
|
+
mrr: positiveCasesCount > 0 ? Number((reciprocalRankSum / positiveCasesCount).toFixed(4)) : 1,
|
|
2020
|
+
no_match_accuracy: noMatchCasesCount > 0 ? Number((noMatchCorrectCount / noMatchCasesCount).toFixed(4)) : 1,
|
|
2021
|
+
unsupported_request_false_positive_rate:
|
|
2022
|
+
noMatchCasesCount > 0 ? Number((unsupportedFalsePositives / noMatchCasesCount).toFixed(4)) : 0,
|
|
2023
|
+
positive_cases: positiveCasesCount,
|
|
2024
|
+
no_match_cases: noMatchCasesCount,
|
|
2025
|
+
language_coverage: langCounts,
|
|
2026
|
+
metric_definitions: {
|
|
2027
|
+
recall_at_k: '|unique_relevant_in_top_k| / |expected_unique|',
|
|
2028
|
+
precision_at_k: '|unique_relevant_in_top_k| / min(k, |expected_unique|) (target-normalized; never divides by result list length)',
|
|
2029
|
+
standard_precision_at_k: '|unique_relevant_in_top_k| / k (strict IR Precision@k with fixed k denominator)'
|
|
2030
|
+
}
|
|
2031
|
+
};
|
|
2032
|
+
|
|
2033
|
+
return {
|
|
2034
|
+
passed: failures.length === 0,
|
|
2035
|
+
total: (suite.cases || []).length,
|
|
2036
|
+
passed_count: passedCount,
|
|
2037
|
+
metrics,
|
|
2038
|
+
failures
|
|
2039
|
+
};
|
|
2040
|
+
}
|
|
2041
|
+
|
|
2042
|
+
/**
|
|
2043
|
+
* Builds the deterministic map of files to install into `.blendops/catalog/` (for project-local installs)
|
|
2044
|
+
* or `dist/shared-catalog/` (for Claude Desktop / Chat shared catalog archive).
|
|
2045
|
+
* Derived 100% from canonical `registry/*` and `schemas/*` — zero hand-maintained duplicates.
|
|
2046
|
+
*/
|
|
2047
|
+
export function buildSharedCatalogFilesMap(rootDir = DEFAULT_ROOT) {
|
|
2048
|
+
const sourcesRaw = fs.readFileSync(path.join(rootDir, 'registry/knowledge-sources.json'), 'utf8');
|
|
2049
|
+
const knowledgeRaw = fs.readFileSync(path.join(rootDir, 'registry/knowledge-catalog.json'), 'utf8');
|
|
2050
|
+
const recipesRaw = fs.readFileSync(path.join(rootDir, 'registry/recipe-catalog.json'), 'utf8');
|
|
2051
|
+
const indexData = generateCatalogIndexData(rootDir);
|
|
2052
|
+
const indexRaw = JSON.stringify(indexData, null, 2) + '\n';
|
|
2053
|
+
|
|
2054
|
+
const skillsData = readJson(path.join(rootDir, 'registry/skills.json'));
|
|
2055
|
+
const skillsSummary = {
|
|
2056
|
+
schemaVersion: '1.0.0',
|
|
2057
|
+
description: 'Compact canonical 48-skill summary for offline project-local and shared-catalog resolution.',
|
|
2058
|
+
skills: skillsData.skills.map((s) => ({
|
|
2059
|
+
id: s.id,
|
|
2060
|
+
version: s.version || '1.0.0',
|
|
2061
|
+
category: s.category,
|
|
2062
|
+
role: s.role,
|
|
2063
|
+
purpose: s.purpose,
|
|
2064
|
+
capabilityTier: s.capabilityTier,
|
|
2065
|
+
workflow_stage: deriveSkillWorkflowStage(s)
|
|
2066
|
+
}))
|
|
2067
|
+
};
|
|
2068
|
+
const skillsSummaryRaw = JSON.stringify(skillsSummary, null, 2) + '\n';
|
|
2069
|
+
|
|
2070
|
+
const sourcesSchemaRaw = fs.readFileSync(path.join(rootDir, 'schemas/knowledge-source-registry.schema.json'), 'utf8');
|
|
2071
|
+
const knowledgeSchemaRaw = fs.readFileSync(path.join(rootDir, 'schemas/knowledge-record.schema.json'), 'utf8');
|
|
2072
|
+
const recipeSchemaRaw = fs.readFileSync(path.join(rootDir, 'schemas/recipe-record.schema.json'), 'utf8');
|
|
2073
|
+
const sceneSpecSchemaPath = path.join(rootDir, 'schemas/scene-spec.schema.json');
|
|
2074
|
+
const executionPlanSchemaPath = path.join(rootDir, 'schemas/execution-plan.schema.json');
|
|
2075
|
+
const runtimeOperationsPath = path.join(rootDir, 'registry/runtime-operations.json');
|
|
2076
|
+
const runtimeCapabilityPolicyPath = path.join(rootDir, 'registry/runtime-capability-policy.json');
|
|
2077
|
+
const runtimeSessionSchemaPath = path.join(rootDir, 'schemas/runtime-session.schema.json');
|
|
2078
|
+
const runtimeOperationsSchemaPath = path.join(rootDir, 'schemas/runtime-operations.schema.json');
|
|
2079
|
+
const operationExecutionLedgerSchemaPath = path.join(rootDir, 'schemas/operation-execution-ledger.schema.json');
|
|
2080
|
+
const runtimeEvidencePacketSchemaPath = path.join(rootDir, 'schemas/runtime-evidence-packet.schema.json');
|
|
2081
|
+
const runtimeCapabilityPolicySchemaPath = path.join(rootDir, 'schemas/runtime-capability-policy.schema.json');
|
|
2082
|
+
const runtimeQualificationReportSchemaPath = path.join(rootDir, 'schemas/runtime-qualification-report.schema.json');
|
|
2083
|
+
|
|
2084
|
+
const hasSceneSpecSchema = fs.existsSync(sceneSpecSchemaPath);
|
|
2085
|
+
const hasExecutionPlanSchema = fs.existsSync(executionPlanSchemaPath);
|
|
2086
|
+
const hasRuntimeOperations = fs.existsSync(runtimeOperationsPath);
|
|
2087
|
+
const hasRuntimeCapabilityPolicy = fs.existsSync(runtimeCapabilityPolicyPath);
|
|
2088
|
+
const hasRuntimeSessionSchema = fs.existsSync(runtimeSessionSchemaPath);
|
|
2089
|
+
const hasRuntimeOperationsSchema = fs.existsSync(runtimeOperationsSchemaPath);
|
|
2090
|
+
const hasOperationExecutionLedgerSchema = fs.existsSync(operationExecutionLedgerSchemaPath);
|
|
2091
|
+
const hasRuntimeEvidencePacketSchema = fs.existsSync(runtimeEvidencePacketSchemaPath);
|
|
2092
|
+
const hasRuntimeCapabilityPolicySchema = fs.existsSync(runtimeCapabilityPolicySchemaPath);
|
|
2093
|
+
const hasRuntimeQualificationReportSchema = fs.existsSync(runtimeQualificationReportSchemaPath);
|
|
2094
|
+
|
|
2095
|
+
const fileList = [
|
|
2096
|
+
'README.md',
|
|
2097
|
+
'manifest.json',
|
|
2098
|
+
'knowledge-sources.json',
|
|
2099
|
+
'knowledge-catalog.json',
|
|
2100
|
+
'recipe-catalog.json',
|
|
2101
|
+
'catalog-index.json',
|
|
2102
|
+
'skills-summary.json',
|
|
2103
|
+
...(hasRuntimeOperations ? ['runtime-operations.json'] : []),
|
|
2104
|
+
...(hasRuntimeCapabilityPolicy ? ['runtime-capability-policy.json'] : []),
|
|
2105
|
+
'schemas/knowledge-source-registry.schema.json',
|
|
2106
|
+
'schemas/knowledge-record.schema.json',
|
|
2107
|
+
'schemas/recipe-record.schema.json',
|
|
2108
|
+
...(hasSceneSpecSchema ? ['schemas/scene-spec.schema.json'] : []),
|
|
2109
|
+
...(hasExecutionPlanSchema ? ['schemas/execution-plan.schema.json'] : []),
|
|
2110
|
+
...(hasRuntimeSessionSchema ? ['schemas/runtime-session.schema.json'] : []),
|
|
2111
|
+
...(hasRuntimeOperationsSchema ? ['schemas/runtime-operations.schema.json'] : []),
|
|
2112
|
+
...(hasOperationExecutionLedgerSchema ? ['schemas/operation-execution-ledger.schema.json'] : []),
|
|
2113
|
+
...(hasRuntimeEvidencePacketSchema ? ['schemas/runtime-evidence-packet.schema.json'] : []),
|
|
2114
|
+
...(hasRuntimeCapabilityPolicySchema ? ['schemas/runtime-capability-policy.schema.json'] : []),
|
|
2115
|
+
...(hasRuntimeQualificationReportSchema ? ['schemas/runtime-qualification-report.schema.json'] : [])
|
|
2116
|
+
];
|
|
2117
|
+
|
|
2118
|
+
const manifestObj = {
|
|
2119
|
+
schema_version: '1.0.0',
|
|
2120
|
+
package_name: 'blendops-shared-knowledge-and-recipe-catalog',
|
|
2121
|
+
generated_from: [
|
|
2122
|
+
'registry/knowledge-sources.json',
|
|
2123
|
+
'registry/knowledge-catalog.json',
|
|
2124
|
+
'registry/recipe-catalog.json',
|
|
2125
|
+
'registry/catalog-index.json',
|
|
2126
|
+
'registry/skills.json',
|
|
2127
|
+
...(hasRuntimeOperations ? ['registry/runtime-operations.json'] : []),
|
|
2128
|
+
...(hasRuntimeCapabilityPolicy ? ['registry/runtime-capability-policy.json'] : [])
|
|
2129
|
+
],
|
|
2130
|
+
counts: indexData.counts,
|
|
2131
|
+
version_baseline: readJson(path.join(rootDir, 'registry/knowledge-sources.json')).taxonomy.versionBaseline,
|
|
2132
|
+
truth_state_defaults: {
|
|
2133
|
+
runtime_status: 'Not Run',
|
|
2134
|
+
artifact_status: 'Not Produced'
|
|
2135
|
+
},
|
|
2136
|
+
files: fileList
|
|
2137
|
+
};
|
|
2138
|
+
|
|
2139
|
+
const readmeContent = [
|
|
2140
|
+
'# BlendOps Shared Knowledge & Recipe Catalog',
|
|
2141
|
+
'',
|
|
2142
|
+
'This portable catalog package contains the canonical BlendOps **Knowledge Layer** (`knowledge.*`), **Recipe Layer** (`recipe.*`), **Authoritative Source Registry** (`source.*`), **Typed Runtime Operations Registry** (`op.*`), and **Deterministic Bilingual (EN+VI) Retrieval Index**.',
|
|
2143
|
+
'',
|
|
2144
|
+
'## Contents',
|
|
2145
|
+
'',
|
|
2146
|
+
'- `knowledge-sources.json` — 20 authoritative Blender / Khronos glTF 2.0.1 / OpenSubdiv / MikkTSpace / Filament / Three.js sources and controlled domain taxonomy.',
|
|
2147
|
+
'- `knowledge-catalog.json` — 30 canonical knowledge records across 11 3D/Blender domains.',
|
|
2148
|
+
'- `recipe-catalog.json` — 10 composable multi-stage construction recipes linking required skills, knowledge records, stage gates, validation criteria, and failure recovery modes.',
|
|
2149
|
+
'- `catalog-index.json` — Prebuilt deterministic bilingual (English + Vietnamese) search and cross-reference index.',
|
|
2150
|
+
'- `skills-summary.json` — Compact metadata for all 48 canonical BlendOps skills so local resolution works standalone without requiring the full BlendOps git repository.',
|
|
2151
|
+
'- `runtime-operations.json` — 18 canonical typed runtime operations (`op.inspect.*`, `op.mutate.*`, `op.export.*`, `op.import.*`), upstream tool qualification matrix, and blocked L3 interfaces.',
|
|
2152
|
+
'- `runtime-capability-policy.json` — Governed runtime capability tiers (`L0`–`L3`) and enforcement policy.',
|
|
2153
|
+
'- `schemas/` — JSON Schema Draft 2020-12 definitions for sources, knowledge records, recipes, SceneSpec, ExecutionPlan, RuntimeSession, RuntimeOperations, OperationExecutionLedger, RuntimeEvidencePacket, RuntimeCapabilityPolicy, and RuntimeQualificationReport.',
|
|
2154
|
+
'',
|
|
2155
|
+
'## How Agents Use This Catalog',
|
|
2156
|
+
'',
|
|
2157
|
+
'1. **Project-Local CLI Lookup** (when installed in `.blendops/catalog/`):',
|
|
2158
|
+
' - Search by natural language (English or Vietnamese): `npx blendops catalog-search "<query>" [--project <project-dir>]`',
|
|
2159
|
+
' - Resolve full record & links: `npx blendops catalog-resolve <knowledge.id | recipe.id | source.id> [--project <project-dir>]`',
|
|
2160
|
+
' - Validate catalog integrity: `npx blendops catalog-validate [--project <project-dir>]`',
|
|
2161
|
+
' - Validate SceneSpec & compile ExecutionPlan: `npx blendops scene-spec-validate <spec.json> [--project <project-dir>]` / `npx blendops plan-compile <spec.json> [--project <project-dir>]`',
|
|
2162
|
+
' - Check runtime readiness, qualification & operations: `npx blendops runtime doctor [--project <project-dir>]` / `npx blendops runtime qualify [--project <project-dir>]` / `npx blendops runtime tools [--project <project-dir>]` / `npx blendops operation mappings [--project <project-dir>]` / `npx blendops runtime smoke [--project <project-dir>]`',
|
|
2163
|
+
'2. **Direct File Consumption** (in Claude Desktop / Claude.ai Projects or offline agent context):',
|
|
2164
|
+
' - Attach or inspect `catalog-index.json` to locate matching `knowledge.*` and `recipe.*` IDs by domain, skill, or keyword.',
|
|
2165
|
+
' - Read the corresponding record in `knowledge-catalog.json` or `recipe-catalog.json` before planning or mutating a Blender scene.',
|
|
2166
|
+
'',
|
|
2167
|
+
'## Truth-State & Runtime Boundaries',
|
|
2168
|
+
'',
|
|
2169
|
+
'- **Runtime status**: `Not Run` (default unless backed by a validated runtime evidence packet)',
|
|
2170
|
+
'- **Artifact status**: `Not Produced` (default unless backed by verified on-disk artifact hashes)',
|
|
2171
|
+
'- **Global files touched**: `No`',
|
|
2172
|
+
''
|
|
2173
|
+
].join('\n');
|
|
2174
|
+
|
|
2175
|
+
const filesMap = {
|
|
2176
|
+
'README.md': readmeContent,
|
|
2177
|
+
'manifest.json': JSON.stringify(manifestObj, null, 2) + '\n',
|
|
2178
|
+
'knowledge-sources.json': sourcesRaw,
|
|
2179
|
+
'knowledge-catalog.json': knowledgeRaw,
|
|
2180
|
+
'recipe-catalog.json': recipesRaw,
|
|
2181
|
+
'catalog-index.json': indexRaw,
|
|
2182
|
+
'skills-summary.json': skillsSummaryRaw,
|
|
2183
|
+
'schemas/knowledge-source-registry.schema.json': sourcesSchemaRaw,
|
|
2184
|
+
'schemas/knowledge-record.schema.json': knowledgeSchemaRaw,
|
|
2185
|
+
'schemas/recipe-record.schema.json': recipeSchemaRaw
|
|
2186
|
+
};
|
|
2187
|
+
if (hasRuntimeOperations) {
|
|
2188
|
+
filesMap['runtime-operations.json'] = fs.readFileSync(runtimeOperationsPath, 'utf8');
|
|
2189
|
+
}
|
|
2190
|
+
if (hasRuntimeCapabilityPolicy) {
|
|
2191
|
+
filesMap['runtime-capability-policy.json'] = fs.readFileSync(runtimeCapabilityPolicyPath, 'utf8');
|
|
2192
|
+
}
|
|
2193
|
+
if (hasSceneSpecSchema) {
|
|
2194
|
+
filesMap['schemas/scene-spec.schema.json'] = fs.readFileSync(sceneSpecSchemaPath, 'utf8');
|
|
2195
|
+
}
|
|
2196
|
+
if (hasExecutionPlanSchema) {
|
|
2197
|
+
filesMap['schemas/execution-plan.schema.json'] = fs.readFileSync(executionPlanSchemaPath, 'utf8');
|
|
2198
|
+
}
|
|
2199
|
+
if (hasRuntimeSessionSchema) {
|
|
2200
|
+
filesMap['schemas/runtime-session.schema.json'] = fs.readFileSync(runtimeSessionSchemaPath, 'utf8');
|
|
2201
|
+
}
|
|
2202
|
+
if (hasRuntimeOperationsSchema) {
|
|
2203
|
+
filesMap['schemas/runtime-operations.schema.json'] = fs.readFileSync(runtimeOperationsSchemaPath, 'utf8');
|
|
2204
|
+
}
|
|
2205
|
+
if (hasOperationExecutionLedgerSchema) {
|
|
2206
|
+
filesMap['schemas/operation-execution-ledger.schema.json'] = fs.readFileSync(operationExecutionLedgerSchemaPath, 'utf8');
|
|
2207
|
+
}
|
|
2208
|
+
if (hasRuntimeEvidencePacketSchema) {
|
|
2209
|
+
filesMap['schemas/runtime-evidence-packet.schema.json'] = fs.readFileSync(runtimeEvidencePacketSchemaPath, 'utf8');
|
|
2210
|
+
}
|
|
2211
|
+
if (hasRuntimeCapabilityPolicySchema) {
|
|
2212
|
+
filesMap['schemas/runtime-capability-policy.schema.json'] = fs.readFileSync(runtimeCapabilityPolicySchemaPath, 'utf8');
|
|
2213
|
+
}
|
|
2214
|
+
if (hasRuntimeQualificationReportSchema) {
|
|
2215
|
+
filesMap['schemas/runtime-qualification-report.schema.json'] = fs.readFileSync(runtimeQualificationReportSchemaPath, 'utf8');
|
|
2216
|
+
}
|
|
2217
|
+
return filesMap;
|
|
2218
|
+
}
|
|
2219
|
+
|
|
2220
|
+
export function buildAllCatalogArtifacts(rootDir = DEFAULT_ROOT, options = {}) {
|
|
2221
|
+
const validation = validateKnowledgeAndRecipeCatalogs(rootDir);
|
|
2222
|
+
if (!validation.valid) {
|
|
2223
|
+
throw new Error(`Catalog validation failed:\n- ${validation.errors.join('\n- ')}`);
|
|
2224
|
+
}
|
|
2225
|
+
|
|
2226
|
+
const indexData = generateCatalogIndexData(rootDir);
|
|
2227
|
+
const catalogMd = renderKnowledgeAndRecipeCatalogMarkdown(rootDir);
|
|
2228
|
+
const auditsDir = path.join(rootDir, 'docs/audits');
|
|
2229
|
+
|
|
2230
|
+
if (options.checkOnly) {
|
|
2231
|
+
const indexPath = path.join(rootDir, 'registry/catalog-index.json');
|
|
2232
|
+
const docPath = path.join(rootDir, 'docs/knowledge-and-recipe-catalog.md');
|
|
2233
|
+
const expectedIndex = JSON.stringify(indexData, null, 2) + '\n';
|
|
2234
|
+
const actualIndex = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '';
|
|
2235
|
+
const expectedDoc = catalogMd;
|
|
2236
|
+
const actualDoc = fs.existsSync(docPath) ? fs.readFileSync(docPath, 'utf8') : '';
|
|
2237
|
+
let auditInSync = true;
|
|
2238
|
+
if (fs.existsSync(auditsDir)) {
|
|
2239
|
+
const auditData = buildSkillArchitectureAuditData(rootDir);
|
|
2240
|
+
const expectedAuditJson = JSON.stringify(auditData, null, 2) + '\n';
|
|
2241
|
+
const actualAuditJson = fs.existsSync(path.join(auditsDir, 'skill-architecture-audit.json'))
|
|
2242
|
+
? fs.readFileSync(path.join(auditsDir, 'skill-architecture-audit.json'), 'utf8')
|
|
2243
|
+
: '';
|
|
2244
|
+
const expectedAuditMd = renderSkillArchitectureAuditMarkdown(auditData);
|
|
2245
|
+
const actualAuditMd = fs.existsSync(path.join(auditsDir, 'skill-architecture-audit.md'))
|
|
2246
|
+
? fs.readFileSync(path.join(auditsDir, 'skill-architecture-audit.md'), 'utf8')
|
|
2247
|
+
: '';
|
|
2248
|
+
auditInSync = actualAuditJson === expectedAuditJson && actualAuditMd === expectedAuditMd;
|
|
2249
|
+
}
|
|
2250
|
+
return {
|
|
2251
|
+
ok: actualIndex === expectedIndex && actualDoc === expectedDoc && auditInSync,
|
|
2252
|
+
validation,
|
|
2253
|
+
index_entries: indexData.entries.length
|
|
2254
|
+
};
|
|
2255
|
+
}
|
|
2256
|
+
|
|
2257
|
+
writeJsonStable(path.join(rootDir, 'registry/catalog-index.json'), indexData);
|
|
2258
|
+
fs.writeFileSync(path.join(rootDir, 'docs/knowledge-and-recipe-catalog.md'), catalogMd, 'utf8');
|
|
2259
|
+
|
|
2260
|
+
if (fs.existsSync(auditsDir)) {
|
|
2261
|
+
const auditData = buildSkillArchitectureAuditData(rootDir);
|
|
2262
|
+
writeJsonStable(path.join(auditsDir, 'skill-architecture-audit.json'), auditData);
|
|
2263
|
+
const auditMd = renderSkillArchitectureAuditMarkdown(auditData);
|
|
2264
|
+
fs.writeFileSync(path.join(auditsDir, 'skill-architecture-audit.md'), auditMd, 'utf8');
|
|
2265
|
+
}
|
|
2266
|
+
|
|
2267
|
+
return {
|
|
2268
|
+
ok: true,
|
|
2269
|
+
validation,
|
|
2270
|
+
index_entries: indexData.entries.length
|
|
2271
|
+
};
|
|
2272
|
+
}
|
|
2273
|
+
|
|
2274
|
+
function main() {
|
|
2275
|
+
const args = process.argv.slice(2);
|
|
2276
|
+
const mode = args[0] || '--build';
|
|
2277
|
+
|
|
2278
|
+
if (mode === '--build') {
|
|
2279
|
+
const result = buildAllCatalogArtifacts(DEFAULT_ROOT);
|
|
2280
|
+
const evalResult = fs.existsSync(path.join(DEFAULT_ROOT, 'evals/catalog-retrieval-evals.json'))
|
|
2281
|
+
? runCatalogRetrievalEvals(DEFAULT_ROOT)
|
|
2282
|
+
: { passed: true, total: 0, passed_count: 0, failures: [] };
|
|
2283
|
+
if (!evalResult.passed) {
|
|
2284
|
+
console.error('Catalog retrieval evals failed:', evalResult.failures);
|
|
2285
|
+
process.exit(1);
|
|
2286
|
+
}
|
|
2287
|
+
console.log(
|
|
2288
|
+
`Built knowledge & recipe catalog artifacts (${result.validation.counts.knowledge_records} knowledge records, ${result.validation.counts.recipes} recipes, ${result.validation.counts.sources} sources; ${evalResult.passed_count}/${evalResult.total} retrieval evals passed).`
|
|
2289
|
+
);
|
|
2290
|
+
return;
|
|
2291
|
+
}
|
|
2292
|
+
|
|
2293
|
+
if (mode === '--check' || mode === '--validate') {
|
|
2294
|
+
const validation = validateKnowledgeAndRecipeCatalogs(DEFAULT_ROOT);
|
|
2295
|
+
if (!validation.valid) {
|
|
2296
|
+
console.error('Catalog validation errors:\n- ' + validation.errors.join('\n- '));
|
|
2297
|
+
process.exit(1);
|
|
2298
|
+
}
|
|
2299
|
+
const indexPath = path.join(DEFAULT_ROOT, 'registry/catalog-index.json');
|
|
2300
|
+
const docPath = path.join(DEFAULT_ROOT, 'docs/knowledge-and-recipe-catalog.md');
|
|
2301
|
+
if (!fs.existsSync(indexPath) || !fs.existsSync(docPath)) {
|
|
2302
|
+
console.error('Missing generated catalog artifacts (registry/catalog-index.json or docs/knowledge-and-recipe-catalog.md).');
|
|
2303
|
+
process.exit(1);
|
|
2304
|
+
}
|
|
2305
|
+
const expectedIndex = JSON.stringify(generateCatalogIndexData(DEFAULT_ROOT), null, 2) + '\n';
|
|
2306
|
+
const actualIndex = fs.readFileSync(indexPath, 'utf8');
|
|
2307
|
+
if (actualIndex !== expectedIndex) {
|
|
2308
|
+
console.error('registry/catalog-index.json is out of sync. Run `npm run catalog:build`.');
|
|
2309
|
+
process.exit(1);
|
|
2310
|
+
}
|
|
2311
|
+
const expectedDoc = renderKnowledgeAndRecipeCatalogMarkdown(DEFAULT_ROOT);
|
|
2312
|
+
const actualDoc = fs.readFileSync(docPath, 'utf8');
|
|
2313
|
+
if (actualDoc !== expectedDoc) {
|
|
2314
|
+
console.error('docs/knowledge-and-recipe-catalog.md is out of sync. Run `npm run catalog:build`.');
|
|
2315
|
+
process.exit(1);
|
|
2316
|
+
}
|
|
2317
|
+
const auditsDir = path.join(DEFAULT_ROOT, 'docs/audits');
|
|
2318
|
+
if (fs.existsSync(auditsDir)) {
|
|
2319
|
+
const auditData = buildSkillArchitectureAuditData(DEFAULT_ROOT);
|
|
2320
|
+
const expectedAuditJson = JSON.stringify(auditData, null, 2) + '\n';
|
|
2321
|
+
const actualAuditJson = fs.existsSync(path.join(auditsDir, 'skill-architecture-audit.json'))
|
|
2322
|
+
? fs.readFileSync(path.join(auditsDir, 'skill-architecture-audit.json'), 'utf8')
|
|
2323
|
+
: '';
|
|
2324
|
+
const expectedAuditMd = renderSkillArchitectureAuditMarkdown(auditData);
|
|
2325
|
+
const actualAuditMd = fs.existsSync(path.join(auditsDir, 'skill-architecture-audit.md'))
|
|
2326
|
+
? fs.readFileSync(path.join(auditsDir, 'skill-architecture-audit.md'), 'utf8')
|
|
2327
|
+
: '';
|
|
2328
|
+
if (actualAuditJson !== expectedAuditJson || actualAuditMd !== expectedAuditMd) {
|
|
2329
|
+
console.error('docs/audits/skill-architecture-audit.{json,md} is out of sync. Run `npm run catalog:build`.');
|
|
2330
|
+
process.exit(1);
|
|
2331
|
+
}
|
|
2332
|
+
}
|
|
2333
|
+
if (fs.existsSync(path.join(DEFAULT_ROOT, 'evals/catalog-retrieval-evals.json'))) {
|
|
2334
|
+
const evalResult = runCatalogRetrievalEvals(DEFAULT_ROOT);
|
|
2335
|
+
if (!evalResult.passed) {
|
|
2336
|
+
console.error('Catalog retrieval eval failures:\n- ' + evalResult.failures.join('\n- '));
|
|
2337
|
+
process.exit(1);
|
|
2338
|
+
}
|
|
2339
|
+
}
|
|
2340
|
+
console.log(
|
|
2341
|
+
`Catalog check passed (${validation.counts.knowledge_records} knowledge records, ${validation.counts.recipes} recipes, ${validation.counts.sources} sources).`
|
|
2342
|
+
);
|
|
2343
|
+
return;
|
|
2344
|
+
}
|
|
2345
|
+
|
|
2346
|
+
if (mode === '--eval') {
|
|
2347
|
+
const evalResult = runCatalogRetrievalEvals(DEFAULT_ROOT);
|
|
2348
|
+
if (!evalResult.passed) {
|
|
2349
|
+
console.error(JSON.stringify(evalResult, null, 2));
|
|
2350
|
+
process.exit(1);
|
|
2351
|
+
}
|
|
2352
|
+
console.log(JSON.stringify(evalResult, null, 2));
|
|
2353
|
+
return;
|
|
2354
|
+
}
|
|
2355
|
+
|
|
2356
|
+
if (mode === '--search') {
|
|
2357
|
+
const query = args.slice(1).join(' ');
|
|
2358
|
+
console.log(JSON.stringify(searchCatalog(DEFAULT_ROOT, query), null, 2));
|
|
2359
|
+
return;
|
|
2360
|
+
}
|
|
2361
|
+
|
|
2362
|
+
if (mode === '--resolve') {
|
|
2363
|
+
const id = args[1] || '';
|
|
2364
|
+
const res = resolveCatalogRecord(DEFAULT_ROOT, id);
|
|
2365
|
+
console.log(JSON.stringify(res, null, 2));
|
|
2366
|
+
if (!res.found) process.exit(1);
|
|
2367
|
+
return;
|
|
2368
|
+
}
|
|
2369
|
+
|
|
2370
|
+
console.error(`Unknown option: ${mode}`);
|
|
2371
|
+
process.exit(1);
|
|
2372
|
+
}
|
|
2373
|
+
|
|
2374
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
|
|
2375
|
+
main();
|
|
2376
|
+
}
|