@wildo-ai/framework-knowledge 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +34 -0
- package/dist/esm/.builder.pid +9 -0
- package/dist/esm/framework-knowledge.definitions.d.ts +51 -0
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.definitions.js +1571 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -0
- package/dist/esm/framework-knowledge.loader.d.ts +72 -0
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.loader.js +258 -0
- package/dist/esm/framework-knowledge.loader.js.map +1 -0
- package/dist/esm/framework-knowledge.schemas.d.ts +236 -0
- package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -0
- package/dist/esm/framework-knowledge.schemas.js +23 -0
- package/dist/esm/framework-knowledge.schemas.js.map +1 -0
- package/dist/esm/index.d.ts +4 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +4 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +53 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +56 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +200 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +228 -0
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +39 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +39 -0
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +261 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +412 -0
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +61 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +65 -0
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +53 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +54 -0
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +43 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +73 -0
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +53 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +114 -0
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +95 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +102 -0
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +258 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +241 -0
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +241 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +202 -0
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +82 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +89 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +56 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +76 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +30 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +27 -0
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +31 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +26 -0
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +254 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +219 -0
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +180 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +302 -0
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +249 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +286 -0
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +248 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +227 -0
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +45 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +48 -0
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +250 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +218 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -0
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -0
- package/dist/knowledge/manifest.json +45 -0
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +407 -0
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +69 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +556 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +47 -0
- package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +344 -0
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +43 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +259 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +83 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +321 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +79 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +185 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +66 -0
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +737 -0
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +44 -0
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +261 -0
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +57 -0
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +151 -0
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +124 -0
- package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.business-model/method.md +128 -0
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +102 -0
- package/dist/knowledge/playbooks/top_down.business-model/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.capability-map/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.capability-map/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +239 -0
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +73 -0
- package/dist/knowledge/playbooks/top_down.capability-map/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +177 -0
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +95 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/method.md +64 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +49 -0
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +56 -0
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +40 -0
- package/dist/knowledge/playbooks/top_down.market-research/method.md +68 -0
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +42 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +239 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +69 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/method.md +96 -0
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +77 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +53 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +61 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +280 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +87 -0
- package/dist/knowledge/playbooks/top_down.scope-roadmap/structured-artifact-action.json +1 -0
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +204 -0
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +54 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +146 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +120 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/structured-artifact-action.json +1 -0
- package/dist/knowledge/references/application.database.migration-change-risk.md +28 -0
- package/dist/knowledge/references/assertions.authored-metadata.config.md +90 -0
- package/dist/knowledge/references/assertions.behaviors.wire-contracts.md +223 -0
- package/dist/knowledge/references/assertions.references.conventions.md +92 -0
- package/dist/knowledge/references/assertions.snapshot.validation.md +317 -0
- package/dist/knowledge/references/assertions.specification.config.md +287 -0
- package/dist/knowledge/references/brand.asset.config.md +167 -0
- package/dist/knowledge/references/brand.authored-metadata.config.md +51 -0
- package/dist/knowledge/references/brand.logo-direction.config.md +88 -0
- package/dist/knowledge/references/brand.name.config.md +46 -0
- package/dist/knowledge/references/brand.snapshot.config.md +76 -0
- package/dist/knowledge/references/brand.snapshot.validation.md +446 -0
- package/dist/knowledge/references/brand.visual-tone.config.md +56 -0
- package/dist/knowledge/references/build-plan.task-graph.config.md +198 -0
- package/dist/knowledge/references/business-model.authored-metadata.config.md +65 -0
- package/dist/knowledge/references/business-model.pricing-plan.config.md +122 -0
- package/dist/knowledge/references/business-model.references.conventions.md +99 -0
- package/dist/knowledge/references/business-model.snapshot.config.md +121 -0
- package/dist/knowledge/references/business-model.snapshot.validation.md +325 -0
- package/dist/knowledge/references/cli.market.generate-command.md +230 -0
- package/dist/knowledge/references/cli.market.utils.md +147 -0
- package/dist/knowledge/references/companion.introspection.behaviors.market.md +90 -0
- package/dist/knowledge/references/companion.introspection.handlers.market.md +42 -0
- package/dist/knowledge/references/companion.market.generation-service.md +270 -0
- package/dist/knowledge/references/companion.market.prompt-renderer.md +244 -0
- package/dist/knowledge/references/companion.technical-doc.service.md +809 -0
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +125 -0
- package/dist/knowledge/references/engine.client-bundle.discipline.md +130 -0
- package/dist/knowledge/references/engine.client-bundle.external-connectors-public.discipline.md +55 -0
- package/dist/knowledge/references/engine.saas-technical-doc.config.md +215 -0
- package/dist/knowledge/references/engine.saas-website.config.md +331 -0
- package/dist/knowledge/references/example.authorization.unit-narrowing.declaration.md +24 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +55 -0
- package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +35 -0
- package/dist/knowledge/references/example.backend.operation.error-throw.md +17 -0
- package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +63 -0
- package/dist/knowledge/references/example.config.app-shell.full.md +147 -0
- package/dist/knowledge/references/example.config.app-shell.hosted-components.md +45 -0
- package/dist/knowledge/references/example.config.app-shell.quick-switcher-fields.md +37 -0
- package/dist/knowledge/references/example.config.backend.billing-enable.md +20 -0
- package/dist/knowledge/references/example.config.backend.required-floors.md +46 -0
- package/dist/knowledge/references/example.config.design-system.full.md +162 -0
- package/dist/knowledge/references/example.config.navigation.full.md +71 -0
- package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +27 -0
- package/dist/knowledge/references/example.data-seeding.minimal.md +114 -0
- package/dist/knowledge/references/example.email.template.minimal.md +54 -0
- package/dist/knowledge/references/example.engine.component-registration.lazy-load.md +16 -0
- package/dist/knowledge/references/example.engine.product-definitions.feature-and-profiles.md +146 -0
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +196 -0
- package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +174 -0
- package/dist/knowledge/references/example.i18n.label-generation.engine-barrel.md +15 -0
- package/dist/knowledge/references/example.infra.cdn.cloudflare.md +23 -0
- package/dist/knowledge/references/example.infra.cdn.generic.md +17 -0
- package/dist/knowledge/references/example.infra.environment-config.local.md +250 -0
- package/dist/knowledge/references/example.market.alternative.in-house-build.md +49 -0
- package/dist/knowledge/references/example.market.authored-metadata.md +32 -0
- package/dist/knowledge/references/example.market.buying-journey.core-icp.md +140 -0
- package/dist/knowledge/references/example.market.category.config.md +71 -0
- package/dist/knowledge/references/example.market.channel.community.md +39 -0
- package/dist/knowledge/references/example.market.feature-benefit.kano-threshold.md +67 -0
- package/dist/knowledge/references/example.market.feature-benefit.pain-reliever.md +65 -0
- package/dist/knowledge/references/example.market.icp.anti-target.md +47 -0
- package/dist/knowledge/references/example.market.icp.individual.md +82 -0
- package/dist/knowledge/references/example.market.icp.legal-entity-with-geographies.md +95 -0
- package/dist/knowledge/references/example.market.is-benefit-available.composition.md +40 -0
- package/dist/knowledge/references/example.market.job.emotional.md +27 -0
- package/dist/knowledge/references/example.market.job.functional.md +28 -0
- package/dist/knowledge/references/example.market.message-template.seeds.md +106 -0
- package/dist/knowledge/references/example.market.objection.pricing.md +39 -0
- package/dist/knowledge/references/example.market.persona.dmu-with-inheritance.md +62 -0
- package/dist/knowledge/references/example.market.persona.individual-self.md +51 -0
- package/dist/knowledge/references/example.market.positioning.per-icp.md +103 -0
- package/dist/knowledge/references/example.market.proof.metric.md +39 -0
- package/dist/knowledge/references/example.market.scoring.golden-case.md +46 -0
- package/dist/knowledge/references/example.market.scoring.no-coverage-zero.md +40 -0
- package/dist/knowledge/references/example.market.snapshot-validation.duplicate-journey-stage.md +36 -0
- package/dist/knowledge/references/example.market.snapshot-validation.errors-by-kind.md +55 -0
- package/dist/knowledge/references/example.market.snapshot-validation.objection-proof-benefit-mismatch.md +74 -0
- package/dist/knowledge/references/example.market.snapshot-validation.proof-without-support.md +32 -0
- package/dist/knowledge/references/example.market.snapshot-validation.threshold-without-job.md +44 -0
- package/dist/knowledge/references/example.market.snapshot.assembled.md +49 -0
- package/dist/knowledge/references/example.market.tone-of-voice.config.md +41 -0
- package/dist/knowledge/references/example.market.trigger.growth-milestone.md +43 -0
- package/dist/knowledge/references/example.module.companion-exports.full.md +142 -0
- package/dist/knowledge/references/example.module.registration.shared.md +16 -0
- package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +47 -0
- package/dist/knowledge/references/example.module.relationships.discriminator.md +25 -0
- package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +25 -0
- package/dist/knowledge/references/example.provider.backend-module-shape.md +110 -0
- package/dist/knowledge/references/example.provider.contribution.backend-billing.md +12 -0
- package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +30 -0
- package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +21 -0
- package/dist/knowledge/references/example.rag.source-fields.declaration.md +83 -0
- package/dist/knowledge/references/example.rate-limit.custom-controller-surface.md +25 -0
- package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +24 -0
- package/dist/knowledge/references/example.resource.add-field.priority-enum.md +19 -0
- package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +21 -0
- package/dist/knowledge/references/example.resource.config-wiring.fk-relationship.md +33 -0
- package/dist/knowledge/references/example.resource.custom-view.read-host.md +28 -0
- package/dist/knowledge/references/example.resource.mcp-exposure.md +65 -0
- package/dist/knowledge/references/example.resource.reference-constraints.role-constrained.md +27 -0
- package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +22 -0
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +43 -0
- package/dist/knowledge/references/example.spec.composite-view.workspace.md +72 -0
- package/dist/knowledge/references/example.spec.feature.flag-with-codehandling.md +64 -0
- package/dist/knowledge/references/example.spec.frontend-component.prop-vocabulary.md +88 -0
- package/dist/knowledge/references/example.spec.resource.semantic-field.md +23 -0
- package/dist/knowledge/references/example.views.app-level.composite-views-config.md +19 -0
- package/dist/knowledge/references/example.views.chart-view.resource-owned.md +69 -0
- package/dist/knowledge/references/example.views.composite-view.host-embeds.md +31 -0
- package/dist/knowledge/references/example.views.composite-view.workspace.md +65 -0
- package/dist/knowledge/references/example.views.custom-view.execution-host.md +41 -0
- package/dist/knowledge/references/example.views.execution-view.resource-owned.md +25 -0
- package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +42 -0
- package/dist/knowledge/references/market.alternative.config.md +68 -0
- package/dist/knowledge/references/market.alternative.kind.md +32 -0
- package/dist/knowledge/references/market.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/market.buying-journey.config.md +43 -0
- package/dist/knowledge/references/market.buying-journey.stage.md +33 -0
- package/dist/knowledge/references/market.category.config.md +63 -0
- package/dist/knowledge/references/market.channel.config.md +59 -0
- package/dist/knowledge/references/market.channel.kind.md +49 -0
- package/dist/knowledge/references/market.context-block.builder.md +544 -0
- package/dist/knowledge/references/market.context-block.response.md +57 -0
- package/dist/knowledge/references/market.feature-benefit.config.md +84 -0
- package/dist/knowledge/references/market.feature-benefit.kano.md +41 -0
- package/dist/knowledge/references/market.gain.config.md +50 -0
- package/dist/knowledge/references/market.generation.response.md +108 -0
- package/dist/knowledge/references/market.icp.config.md +162 -0
- package/dist/knowledge/references/market.icp.geographic-targeting.md +57 -0
- package/dist/knowledge/references/market.inherit-from.md +74 -0
- package/dist/knowledge/references/market.is-benefit-available.md +58 -0
- package/dist/knowledge/references/market.job.config.md +48 -0
- package/dist/knowledge/references/market.message-template.config.md +86 -0
- package/dist/knowledge/references/market.objection.config.md +56 -0
- package/dist/knowledge/references/market.objection.kind.md +34 -0
- package/dist/knowledge/references/market.pain.config.md +50 -0
- package/dist/knowledge/references/market.persona.config.md +64 -0
- package/dist/knowledge/references/market.positioning.config.md +84 -0
- package/dist/knowledge/references/market.proof.config.md +48 -0
- package/dist/knowledge/references/market.proof.kind.md +34 -0
- package/dist/knowledge/references/market.references.weighted-edges.md +105 -0
- package/dist/knowledge/references/market.scoring.fit.md +215 -0
- package/dist/knowledge/references/market.snapshot.config.md +34 -0
- package/dist/knowledge/references/market.snapshot.validation.md +1171 -0
- package/dist/knowledge/references/market.tone-of-voice.config.md +80 -0
- package/dist/knowledge/references/market.trigger.config.md +45 -0
- package/dist/knowledge/references/market.trigger.kind.md +35 -0
- package/dist/knowledge/references/placement-plan.config.md +330 -0
- package/dist/knowledge/references/platform.config.application-database.md +74 -0
- package/dist/knowledge/references/platform.config.application-modules.md +30 -0
- package/dist/knowledge/references/platform.config.backing-services.md +266 -0
- package/dist/knowledge/references/platform.config.cdn.md +167 -0
- package/dist/knowledge/references/platform.config.environment.deployment.md +263 -0
- package/dist/knowledge/references/platform.config.saas.md +405 -0
- package/dist/knowledge/references/presets.models.design-system.configuration.md +59 -0
- package/dist/knowledge/references/presets.models.design-system.source-config.md +72 -0
- package/dist/knowledge/references/presets.models.labelling.sections.md +64 -0
- package/dist/knowledge/references/presets.models.material.profile-contract.md +192 -0
- package/dist/knowledge/references/presets.models.material.runtime-policy.md +60 -0
- package/dist/knowledge/references/presets.models.surface-policy.defaults.md +613 -0
- package/dist/knowledge/references/presets.models.surface-policy.md +534 -0
- package/dist/knowledge/references/presets.models.surface-variant.md +56 -0
- package/dist/knowledge/references/requirements.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +68 -0
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +100 -0
- package/dist/knowledge/references/requirements.references.conventions.md +125 -0
- package/dist/knowledge/references/requirements.snapshot.config.md +73 -0
- package/dist/knowledge/references/requirements.snapshot.validation.md +333 -0
- package/dist/knowledge/references/roadmap.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/roadmap.phase.config.md +149 -0
- package/dist/knowledge/references/roadmap.references.conventions.md +89 -0
- package/dist/knowledge/references/roadmap.snapshot.config.md +65 -0
- package/dist/knowledge/references/roadmap.snapshot.validation.md +325 -0
- package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +32 -0
- package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +38 -0
- package/dist/knowledge/references/saas.backend.billing.resolution-failure-reasons.md +45 -0
- package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +53 -0
- package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +120 -0
- package/dist/knowledge/references/saas.backend.domain-module.md +237 -0
- package/dist/knowledge/references/saas.backend.email-template.definition.md +69 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +89 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +118 -0
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +82 -0
- package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +48 -0
- package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +39 -0
- package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +67 -0
- package/dist/knowledge/references/saas.backend.pdf-template.bindings.md +52 -0
- package/dist/knowledge/references/saas.backend.pdf-template.definition.md +113 -0
- package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +75 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +994 -0
- package/dist/knowledge/references/saas.data-seeding.admin-endpoints.md +59 -0
- package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +184 -0
- package/dist/knowledge/references/saas.data-seeding.definition-input.md +95 -0
- package/dist/knowledge/references/saas.data-seeding.modes.md +72 -0
- package/dist/knowledge/references/saas.data-seeding.run-ledger.md +198 -0
- package/dist/knowledge/references/saas.data-seeding.run-status.md +35 -0
- package/dist/knowledge/references/saas.data-seeding.schedule.md +91 -0
- package/dist/knowledge/references/saas.data-seeding.scope-iteration-strategy.md +46 -0
- package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +55 -0
- package/dist/knowledge/references/saas.external-providers.document-extraction.applicability.md +26 -0
- package/dist/knowledge/references/saas.external-providers.embeddings.applicability.md +30 -0
- package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +124 -0
- package/dist/knowledge/references/saas.external-providers.llm.operation-key.md +49 -0
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +265 -0
- package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +148 -0
- package/dist/knowledge/references/saas.frontend.app-shell.hosted-components.md +145 -0
- package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +80 -0
- package/dist/knowledge/references/saas.frontend.command-menu.omnibox.md +88 -0
- package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +109 -0
- package/dist/knowledge/references/saas.frontend.component-registration.entry.md +21 -0
- package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +102 -0
- package/dist/knowledge/references/saas.frontend.composite-view.define-helper.md +31 -0
- package/dist/knowledge/references/saas.frontend.domain-module.md +31 -0
- package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +37 -0
- package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.md +172 -0
- package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.per-action-retry-loop.md +115 -0
- package/dist/knowledge/references/saas.frontend.execution-view.definition.md +172 -0
- package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.local-pane.md +109 -0
- package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.md +55 -0
- package/dist/knowledge/references/saas.frontend.execution-view.dirty-state-contract.md +151 -0
- package/dist/knowledge/references/saas.frontend.execution-view.failure-handling-contract.md +302 -0
- package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.md +89 -0
- package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.md +231 -0
- package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator.md +174 -0
- package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.md +96 -0
- package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.resolution.md +45 -0
- package/dist/knowledge/references/saas.frontend.execution-view.outcome-emission-contract.md +71 -0
- package/dist/knowledge/references/saas.frontend.execution-view.participation-and-anchor.md +80 -0
- package/dist/knowledge/references/saas.frontend.execution-view.three-zone-contract.md +147 -0
- package/dist/knowledge/references/saas.frontend.flows-actors-view.md +40 -0
- package/dist/knowledge/references/saas.frontend.form-fields.file-provider-constraints.md +80 -0
- package/dist/knowledge/references/saas.frontend.full-custom-view.definition.md +64 -0
- package/dist/knowledge/references/saas.frontend.inserted-view.identity-bindings-descriptor.md +149 -0
- package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +63 -0
- package/dist/knowledge/references/saas.frontend.quick-switcher.scope-field.md +102 -0
- package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +86 -0
- package/dist/knowledge/references/saas.frontend.related-resource-preview.md +23 -0
- package/dist/knowledge/references/saas.frontend.related-resource-sections.md +28 -0
- package/dist/knowledge/references/saas.frontend.resource-header-title.md +43 -0
- package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +215 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +531 -0
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +210 -0
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-preset-map.md +39 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +58 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +118 -0
- package/dist/knowledge/references/saas.frontend.view-definition-scope.md +42 -0
- package/dist/knowledge/references/saas.market.generation-agent.md +104 -0
- package/dist/knowledge/references/saas.models.core-resource-operation.md +86 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +395 -0
- package/dist/knowledge/references/saas.models.engine-capabilities.md +114 -0
- package/dist/knowledge/references/saas.models.error-type.md +45 -0
- package/dist/knowledge/references/saas.models.external-data-pipeline.md +162 -0
- package/dist/knowledge/references/saas.models.feature-limit-semantic.md +51 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +127 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +115 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-invocation.md +52 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-prompt-spec.md +188 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +237 -0
- package/dist/knowledge/references/saas.models.navigation.layout.md +149 -0
- package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +22 -0
- package/dist/knowledge/references/saas.models.organization-unit-narrowing-declaration.md +42 -0
- package/dist/knowledge/references/saas.models.polymorphism.optout-business-key.md +62 -0
- package/dist/knowledge/references/saas.models.polymorphism.variant-definition.md +74 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +97 -0
- package/dist/knowledge/references/saas.models.rate-limit-configuration.md +67 -0
- package/dist/knowledge/references/saas.models.relationship-handling-contract.md +30 -0
- package/dist/knowledge/references/saas.models.relationship-handling-settings.md +62 -0
- package/dist/knowledge/references/saas.models.relationship-nature-and-models.md +112 -0
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +431 -0
- package/dist/knowledge/references/saas.models.resource-config.forwarded-label.md +88 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +89 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-base.md +79 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +49 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-path.md +27 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-union.md +26 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-variant-for-key.md +62 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +124 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-relationships-buckets.md +38 -0
- package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +69 -0
- package/dist/knowledge/references/saas.models.resource-config.searchable-relation.md +89 -0
- package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +121 -0
- package/dist/knowledge/references/saas.models.resource-config.token-generation.md +145 -0
- package/dist/knowledge/references/saas.models.resource-field-identifier.md +25 -0
- package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +77 -0
- package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +58 -0
- package/dist/knowledge/references/saas.models.resource-primary-scope.md +36 -0
- package/dist/knowledge/references/saas.models.resource-relationship-access-scope.md +26 -0
- package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +100 -0
- package/dist/knowledge/references/saas.models.resource-relationship-cardinality.md +57 -0
- package/dist/knowledge/references/saas.models.resource-relationship-declaration.md +69 -0
- package/dist/knowledge/references/saas.models.resource-relationship-resolved-semantics.md +60 -0
- package/dist/knowledge/references/saas.models.resource-relationship-schema.md +172 -0
- package/dist/knowledge/references/saas.models.resource-server-instance.md +109 -0
- package/dist/knowledge/references/saas.models.resource-type.md +24 -0
- package/dist/knowledge/references/saas.models.schema-family-builder.md +242 -0
- package/dist/knowledge/references/saas.models.scope-membership.md +143 -0
- package/dist/knowledge/references/saas.models.shared-domain-module.md +36 -0
- package/dist/knowledge/references/saas.models.shared-saas-module.md +36 -0
- package/dist/knowledge/references/saas.public-runtime.contract.md +229 -0
- package/dist/knowledge/references/saas.rag.retrieval-bounds.md +106 -0
- package/dist/knowledge/references/saas.rag.retrieval-refusals.md +89 -0
- package/dist/knowledge/references/saas.rag.retrieval-request.md +130 -0
- package/dist/knowledge/references/saas.rag.retrieval-result.md +147 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +54 -0
- package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +59 -0
- package/dist/knowledge/references/saas.specifications.application-document-publication.contract.md +74 -0
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +1158 -0
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +2602 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +180 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +138 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-rating.md +47 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-article.md +49 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-blog-posting.md +62 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-breadcrumb-list.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-faq-page.md +51 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-offer.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-organization.md +48 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +59 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-review.md +46 -0
- package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-website.md +46 -0
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +530 -0
- package/dist/knowledge/references/saas.specifications.composite-view-specification.md +49 -0
- package/dist/knowledge/references/saas.specifications.error-message-specification.md +92 -0
- package/dist/knowledge/references/saas.specifications.family-specifications.md +109 -0
- package/dist/knowledge/references/saas.specifications.feature-specification.md +93 -0
- package/dist/knowledge/references/saas.specifications.frontend-component-spec-factory.md +113 -0
- package/dist/knowledge/references/saas.specifications.frontend-component-spec-model.md +366 -0
- package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +41 -0
- package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +1978 -0
- package/dist/knowledge/references/saas.specifications.resource-pdf-template-spec.md +58 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-code-handling.md +49 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +156 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +171 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-frontend-config-type.md +54 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +171 -0
- package/dist/knowledge/references/saas.website.astro.bridge.md +262 -0
- package/dist/knowledge/references/saas.website.astro.head-renderer.md +271 -0
- package/dist/knowledge/references/saas.website.astro.headers-renderer.md +41 -0
- package/dist/knowledge/references/saas.website.astro.i18n-helper.md +121 -0
- package/dist/knowledge/references/saas.website.astro.label-key-collector.md +117 -0
- package/dist/knowledge/references/saas.website.astro.label-loader.md +377 -0
- package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +46 -0
- package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +90 -0
- package/dist/knowledge/references/saas.website.astro.robots-renderer.md +174 -0
- package/dist/knowledge/references/saas.website.astro.runtime-helper.md +187 -0
- package/dist/knowledge/references/saas.website.astro.site-context.md +141 -0
- package/dist/knowledge/references/saas.website.astro.sitemap-coverage.md +188 -0
- package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +174 -0
- package/dist/knowledge/references/saas.website.blog.bridge.md +396 -0
- package/dist/knowledge/references/saas.website.blog.collection-config.md +180 -0
- package/dist/knowledge/references/saas.website.blog.frontmatter.md +116 -0
- package/dist/knowledge/references/saas.website.blog.head-renderer.md +292 -0
- package/dist/knowledge/references/saas.website.blog.mdx-provider.md +100 -0
- package/dist/knowledge/references/saas.website.blog.post-renderer.md +291 -0
- package/dist/knowledge/references/saas.website.design-tokens.bundle.md +29 -0
- package/dist/knowledge/references/saas.website.design-tokens.colors.md +64 -0
- package/dist/knowledge/references/saas.website.design-tokens.radius.md +38 -0
- package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +98 -0
- package/dist/knowledge/references/saas.website.factories.define-section.md +128 -0
- package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +36 -0
- package/dist/knowledge/references/saas.website.label-keys.format.md +67 -0
- package/dist/knowledge/references/saas.website.label-pack.validator.md +206 -0
- package/dist/knowledge/references/saas.website.page-layout.component.md +217 -0
- package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +47 -0
- package/dist/knowledge/references/saas.website.page-manifest.route-path.md +49 -0
- package/dist/knowledge/references/saas.website.page-manifest.schema.md +186 -0
- package/dist/knowledge/references/saas.website.page-manifest.seo.md +46 -0
- package/dist/knowledge/references/saas.website.page.context.md +57 -0
- package/dist/knowledge/references/saas.website.primitives.button.md +123 -0
- package/dist/knowledge/references/saas.website.primitives.heading.md +103 -0
- package/dist/knowledge/references/saas.website.primitives.image.md +103 -0
- package/dist/knowledge/references/saas.website.primitives.internal-button.md +151 -0
- package/dist/knowledge/references/saas.website.primitives.internal-link.md +193 -0
- package/dist/knowledge/references/saas.website.primitives.link.md +78 -0
- package/dist/knowledge/references/saas.website.primitives.text.md +82 -0
- package/dist/knowledge/references/saas.website.refs.page.md +56 -0
- package/dist/knowledge/references/saas.website.refs.section.md +57 -0
- package/dist/knowledge/references/saas.website.root-config.navigation.md +37 -0
- package/dist/knowledge/references/saas.website.root-config.schema.md +192 -0
- package/dist/knowledge/references/saas.website.root-config.seo.md +98 -0
- package/dist/knowledge/references/saas.website.routing.localized-path.md +84 -0
- package/dist/knowledge/references/saas.website.runtime.context.md +174 -0
- package/dist/knowledge/references/saas.website.section.component.md +138 -0
- package/dist/knowledge/references/saas.website.section.context.md +63 -0
- package/dist/knowledge/references/saas.website.sections.category-enum.md +72 -0
- package/dist/knowledge/references/saas.website.sections.definition-schema.md +121 -0
- package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +37 -0
- package/dist/knowledge/references/saas.website.seo.robots-config.md +106 -0
- package/dist/knowledge/references/saas.website.seo.sitemap-config.md +73 -0
- package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +71 -0
- package/dist/knowledge/references/saas.website.use-label-by-key.hook.md +45 -0
- package/dist/knowledge/references/saas.website.use-label.hook.md +82 -0
- package/dist/knowledge/references/saas.website.use-page.hook.md +30 -0
- package/dist/knowledge/references/saas.website.use-runtime.hook.md +36 -0
- package/dist/knowledge/references/saas.website.use-section.hook.md +30 -0
- package/dist/knowledge/references/saas.website.use-tokens.hook.md +32 -0
- package/dist/knowledge/references/vision.authored-metadata.config.md +64 -0
- package/dist/knowledge/references/vision.constraint.config.md +66 -0
- package/dist/knowledge/references/vision.idea.config.md +45 -0
- package/dist/knowledge/references/vision.mission.config.md +46 -0
- package/dist/knowledge/references/vision.problem.config.md +51 -0
- package/dist/knowledge/references/vision.references.conventions.md +115 -0
- package/dist/knowledge/references/vision.snapshot.config.md +85 -0
- package/dist/knowledge/references/vision.snapshot.validation.md +226 -0
- package/dist/knowledge/references/vision.success-criterion.config.md +60 -0
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +550 -0
- package/dist/knowledge/references/zod.decorators.conditional-visibility.md +104 -0
- package/dist/knowledge/references/zod.decorators.data-categories.md +197 -0
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +436 -0
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +174 -0
- package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +101 -0
- package/dist/knowledge/references/zod.decorators.field-spec-params.md +317 -0
- package/dist/knowledge/references/zod.decorators.file-generation.md +36 -0
- package/dist/knowledge/references/zod.decorators.file-rag-source.md +56 -0
- package/dist/knowledge/references/zod.decorators.file-schema.md +319 -0
- package/dist/knowledge/references/zod.decorators.foreign-key-display-mode.md +83 -0
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +459 -0
- package/dist/knowledge/references/zod.decorators.primitive-ui.md +123 -0
- package/dist/knowledge/references/zod.decorators.rag-source.md +164 -0
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +122 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +152 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +314 -0
- package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +529 -0
- package/dist/knowledge/references/zod.factories.bigdecimal.md +155 -0
- package/dist/knowledge/references/zod.factories.code.md +127 -0
- package/dist/knowledge/references/zod.factories.duration.md +246 -0
- package/dist/knowledge/references/zod.factories.money.md +166 -0
- package/dist/knowledge/references/zod.factories.phone.md +88 -0
- package/dist/knowledge/references/zod.factories.range.md +174 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +15 -0
- package/dist/knowledge/registries/framework-topics.json +5212 -0
- package/dist/knowledge/registries/playbooks.json +488 -0
- package/dist/knowledge/registries/source-tags.json +7664 -0
- package/dist/knowledge/rules/resource-schema-awareness.md +77 -0
- package/dist/knowledge/skills/INDEX.md +349 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +415 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/examples/domain-use-case-and-admin-task.example.md +49 -0
- package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +52 -0
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +218 -0
- package/dist/knowledge/skills/application-database-migrations/references/framework-application-database-api.md +84 -0
- package/dist/knowledge/skills/application-database-migrations/references/framework-migration-change-risk-api.md +37 -0
- package/dist/knowledge/skills/application-database-migrations/references/migration-refusals.md +64 -0
- package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +323 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +84 -0
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +324 -0
- package/dist/knowledge/skills/backend-addon-wiring/references/backend-di-routing.md +7 -0
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +276 -0
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +374 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +118 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +107 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +134 -0
- package/dist/knowledge/skills/backend-custom-operation/references/operation-file-conventions.md +10 -0
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +192 -0
- package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +55 -0
- package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-asset-api.md +184 -0
- package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +279 -0
- package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +346 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +160 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +518 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +158 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +95 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-publication-contract.md +100 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +1210 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +40 -0
- package/dist/knowledge/skills/config-app-shell/SKILL.md +698 -0
- package/dist/knowledge/skills/config-app-shell/references/app-shell-surfaces.md +5 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +415 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +170 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +212 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-quick-switcher-scope-field-api.md +178 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +424 -0
- package/dist/knowledge/skills/config-design-system/references/design-system-file.md +10 -0
- package/dist/knowledge/skills/config-design-system/references/framework-design-system-configuration-api.md +77 -0
- package/dist/knowledge/skills/config-design-system/references/framework-material-profile-api.md +200 -0
- package/dist/knowledge/skills/config-design-system/references/framework-material-runtime-policy-api.md +68 -0
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +1212 -0
- package/dist/knowledge/skills/config-design-system/references/surface-policy-authoring.md +92 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +249 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +152 -0
- package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +5 -0
- package/dist/knowledge/skills/config-saas/SKILL.md +209 -0
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +221 -0
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +408 -0
- package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +9 -0
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +183 -0
- package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +40 -0
- package/dist/knowledge/skills/configure-billing/SKILL.md +261 -0
- package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +90 -0
- package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +122 -0
- package/dist/knowledge/skills/configure-billing/references/example-provider-contribution-and-backend-config.md +48 -0
- package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +69 -0
- package/dist/knowledge/skills/configure-billing/references/framework-billing-resolution-failure-api.md +57 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +439 -0
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +9 -0
- package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +72 -0
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +62 -0
- package/dist/knowledge/skills/email-labels-authoring/SKILL.md +64 -0
- package/dist/knowledge/skills/email-template-authoring/SKILL.md +62 -0
- package/dist/knowledge/skills/engine-component-registration/SKILL.md +257 -0
- package/dist/knowledge/skills/engine-component-registration/references/component-registration-file.md +7 -0
- package/dist/knowledge/skills/engine-component-registration/references/framework-component-registration-api.md +24 -0
- package/dist/knowledge/skills/engine-product-definitions/SKILL.md +429 -0
- package/dist/knowledge/skills/engine-product-definitions/references/framework-engine-product-definitions-api.md +287 -0
- package/dist/knowledge/skills/engine-product-definitions/references/product-registry-scope.md +5 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +491 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +227 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-named-a2a-agents-contract.md +143 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +368 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +226 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +208 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +286 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +376 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +262 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +130 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-prompt-spec-api.md +214 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +195 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/operation-key-selection.md +60 -0
- package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +237 -0
- package/dist/knowledge/skills/frontend-cdn-publish/references/cloudflare-and-operator-setup.md +56 -0
- package/dist/knowledge/skills/frontend-cdn-publish/references/framework-cdn-config-api.md +176 -0
- package/dist/knowledge/skills/i18n-label-generation/SKILL.md +261 -0
- package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +67 -0
- package/dist/knowledge/skills/i18n-label-generation/references/label-placement.md +7 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +269 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +67 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/references/i18n-routing.md +9 -0
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +245 -0
- package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +67 -0
- package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +17 -0
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +646 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-application-database-api.md +77 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +282 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +265 -0
- package/dist/knowledge/skills/infra-environment-config/references/infra-config-files.md +7 -0
- package/dist/knowledge/skills/journey-approve/SKILL.md +43 -0
- package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +42 -0
- package/dist/knowledge/skills/journey-next/SKILL.md +42 -0
- package/dist/knowledge/skills/journey-report/SKILL.md +43 -0
- package/dist/knowledge/skills/journey-run/SKILL.md +55 -0
- package/dist/knowledge/skills/journey-status/SKILL.md +50 -0
- package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +370 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/initialization-recovery-recipe.md +50 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +409 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +247 -0
- package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +474 -0
- package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +139 -0
- package/dist/knowledge/skills/market-alternatives/SKILL.md +543 -0
- package/dist/knowledge/skills/market-authoring-overview/SKILL.md +354 -0
- package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +138 -0
- package/dist/knowledge/skills/market-authoring-overview/references/framework-market-snapshot-api.md +129 -0
- package/dist/knowledge/skills/market-category/SKILL.md +290 -0
- package/dist/knowledge/skills/market-channels/SKILL.md +361 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +2752 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +2443 -0
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +1484 -0
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +1230 -0
- package/dist/knowledge/skills/market-icp/SKILL.md +625 -0
- package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +352 -0
- package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +415 -0
- package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1439 -0
- package/dist/knowledge/skills/market-persona/SKILL.md +407 -0
- package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +392 -0
- package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +97 -0
- package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +665 -0
- package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +620 -0
- package/dist/knowledge/skills/market-scoring-interpretation/references/framework-scoring-api.md +291 -0
- package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1706 -0
- package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1228 -0
- package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +260 -0
- package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +579 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +318 -0
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +544 -0
- package/dist/knowledge/skills/module-registration/SKILL.md +212 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +366 -0
- package/dist/knowledge/skills/module-registration/references/registry-files.md +9 -0
- package/dist/knowledge/skills/module-relationships/SKILL.md +523 -0
- package/dist/knowledge/skills/module-relationships/references/cross-resource-fk-checklist.md +7 -0
- package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +738 -0
- package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +174 -0
- package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-api.md +203 -0
- package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-spec-api.md +62 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +239 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-file-provider-constraints-api.md +90 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +50 -0
- package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +652 -0
- package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +182 -0
- package/dist/knowledge/skills/rate-limit-authoring/references/scope-key-and-bucket-conventions.md +137 -0
- package/dist/knowledge/skills/resource-add-field/SKILL.md +272 -0
- package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +153 -0
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +845 -0
- package/dist/knowledge/skills/resource-add-module/SKILL.md +322 -0
- package/dist/knowledge/skills/resource-add-module/references/framework-new-module-wiring-api.md +67 -0
- package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +15 -0
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +222 -0
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +540 -0
- package/dist/knowledge/skills/resource-add-resource/references/scaffold-surfaces-checklist.md +25 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +370 -0
- package/dist/knowledge/skills/resource-config-wiring/references/config-change-routing.md +11 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +622 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +248 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +1769 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +1209 -0
- package/dist/knowledge/skills/resource-custom-view/SKILL.md +228 -0
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +693 -0
- package/dist/knowledge/skills/resource-external-data/SKILL.md +349 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +187 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +261 -0
- package/dist/knowledge/skills/resource-external-data/references/lane-selection.md +49 -0
- package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +43 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +308 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-named-mcp-servers-contract.md +166 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +63 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +77 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +90 -0
- package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +424 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/corpus-field-selection.md +90 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +261 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-file-rag-source-api.md +117 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +597 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +181 -0
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +318 -0
- package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +132 -0
- package/dist/knowledge/skills/resource-schema-authoring/examples/basic-resource-schema.example.md +62 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +63 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +70 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +559 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +245 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-polymorphic-resources-api.md +147 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +247 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +164 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +327 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +1286 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +1080 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/polymorphic-per-scope-resources.md +75 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/schema-variants-and-discriminators.md +62 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +69 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +45 -0
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +389 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-conditional-visibility-api.md +106 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +176 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +103 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-foreign-key-ui-api.md +97 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +839 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +461 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +125 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +245 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +302 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/ui-layer-boundaries.md +13 -0
- package/dist/knowledge/skills/seeding-authoring/SKILL.md +569 -0
- package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +154 -0
- package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +176 -0
- package/dist/knowledge/skills/seeding-operations/SKILL.md +505 -0
- package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +337 -0
- package/dist/knowledge/skills/seeding-operations/references/data-seeding-cron-scheduler.md +171 -0
- package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +662 -0
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +134 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +65 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +127 -0
- package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +726 -0
- package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +242 -0
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +362 -0
- package/dist/knowledge/skills/spec-companion-exports/references/companion-export-checklist.md +8 -0
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +533 -0
- package/dist/knowledge/skills/spec-component-update/SKILL.md +315 -0
- package/dist/knowledge/skills/spec-component-update/references/component-spec-props.md +8 -0
- package/dist/knowledge/skills/spec-component-update/references/framework-frontend-component-spec-api.md +481 -0
- package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +283 -0
- package/dist/knowledge/skills/spec-composite-view-update/references/composite-spec-sections.md +5 -0
- package/dist/knowledge/skills/spec-composite-view-update/references/framework-composite-view-specification-api.md +51 -0
- package/dist/knowledge/skills/spec-family-update/SKILL.md +300 -0
- package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +13 -0
- package/dist/knowledge/skills/spec-family-update/references/framework-error-message-specifications-api.md +108 -0
- package/dist/knowledge/skills/spec-family-update/references/framework-family-specifications-api.md +111 -0
- package/dist/knowledge/skills/spec-feature-update/SKILL.md +306 -0
- package/dist/knowledge/skills/spec-feature-update/references/feature-spec-scope.md +5 -0
- package/dist/knowledge/skills/spec-feature-update/references/framework-feature-specification-api.md +95 -0
- package/dist/knowledge/skills/spec-resource-update/SKILL.md +220 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +319 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +2610 -0
- package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +12 -0
- package/dist/knowledge/skills/spec-update-after-change/SKILL.md +195 -0
- package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +173 -0
- package/dist/knowledge/skills/spec-update-after-change/references/spec-maintenance-by-surface.md +33 -0
- package/dist/knowledge/skills/spec-update-after-change/references/surface-to-spec-routing.md +14 -0
- package/dist/knowledge/skills/views-add-composite-view/SKILL.md +259 -0
- package/dist/knowledge/skills/views-add-composite-view/references/composite-view-routing.md +10 -0
- package/dist/knowledge/skills/views-add-composite-view/references/framework-inserted-view-identity-api.md +151 -0
- package/dist/knowledge/skills/views-add-custom-view/SKILL.md +225 -0
- package/dist/knowledge/skills/views-add-custom-view/references/custom-view-routing.md +10 -0
- package/dist/knowledge/skills/views-add-custom-view/references/framework-view-scope-and-full-custom-api.md +107 -0
- package/dist/knowledge/skills/views-app-level/SKILL.md +201 -0
- package/dist/knowledge/skills/views-app-level/references/app-level-views-routing.md +9 -0
- package/dist/knowledge/skills/views-app-level/references/framework-view-scope-and-full-custom-api.md +107 -0
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +264 -0
- package/dist/knowledge/skills/views-chart-authoring/references/chart-view-checklist.md +7 -0
- package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +82 -0
- package/dist/knowledge/skills/views-chart-authoring/references/framework-inserted-view-identity-api.md +152 -0
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +302 -0
- package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +23 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +133 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-inserted-view-identity-api.md +152 -0
- package/dist/knowledge/skills/views-execution-authoring/SKILL.md +209 -0
- package/dist/knowledge/skills/views-execution-authoring/references/execution-view-checklist.md +7 -0
- package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +389 -0
- package/dist/knowledge/skills/views-execution-authoring/references/framework-inserted-view-identity-api.md +152 -0
- package/dist/knowledge/skills/website-anonymous-session/SKILL.md +444 -0
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +587 -0
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1426 -0
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +553 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +52 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +357 -0
- package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +511 -0
- package/dist/knowledge/skills/website-factory-advanced/SKILL.md +376 -0
- package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +304 -0
- package/dist/knowledge/skills/website-label-pack/SKILL.md +390 -0
- package/dist/knowledge/skills/website-layout-overrides/SKILL.md +461 -0
- package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +264 -0
- package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +414 -0
- package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +366 -0
- package/dist/knowledge/skills/website-page-authoring/SKILL.md +420 -0
- package/dist/knowledge/skills/website-page-variants/SKILL.md +256 -0
- package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +302 -0
- package/dist/knowledge/skills/website-section-contact/SKILL.md +950 -0
- package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-cta/SKILL.md +822 -0
- package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-faq/SKILL.md +917 -0
- package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +878 -0
- package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +895 -0
- package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +814 -0
- package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-hero/SKILL.md +944 -0
- package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +583 -0
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +934 -0
- package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +912 -0
- package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +579 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +624 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +633 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +193 -0
- package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +790 -0
- package/dist/knowledge/topic-index.json +17510 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -0
- package/dist/tsconfig.tsbuildinfo +1 -0
- package/package.json +49 -0
|
@@ -0,0 +1,2443 @@
|
|
|
1
|
+
# Market Context Behaviors (source)
|
|
2
|
+
|
|
3
|
+
Phase 4.1 introduces a small, deterministic family for prompt
|
|
4
|
+
enrichment: one pure builder (`buildMarketContextBlock`) plus two
|
|
5
|
+
introspection behaviors that expose it over the standard companion
|
|
6
|
+
HTTP/RPC surface. All three are mechanism-only — they pair with a
|
|
7
|
+
`MarketMessageTemplate` and an LLM call (Phase 4.2) to produce
|
|
8
|
+
marketing output.
|
|
9
|
+
|
|
10
|
+
## Pure renderer (source)
|
|
11
|
+
|
|
12
|
+
`buildMarketContextBlock(input)` — pure, deterministic, English
|
|
13
|
+
markdown rendering of a `MarketSnapshot` slice keyed by intent
|
|
14
|
+
(`feature` or `icp`). Returns `{ block, trace }`. The optional
|
|
15
|
+
`outputLanguage` parameter appends a single "Output language"
|
|
16
|
+
instruction; the body itself is never translated (D15).
|
|
17
|
+
|
|
18
|
+
## Import Origins
|
|
19
|
+
|
|
20
|
+
- `@wildo-ai/dev-companion`
|
|
21
|
+
|
|
22
|
+
## Source Excerpts
|
|
23
|
+
|
|
24
|
+
### Origin Package: `@wildo-ai/dev-companion`
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
*
|
|
28
|
+
* Pure builder that renders an English "market context" prose block
|
|
29
|
+
* from a validated `MarketSnapshot`. The block is consumed by:
|
|
30
|
+
*
|
|
31
|
+
* - the dev-companion subprocess behaviors `market-context-for-feature`
|
|
32
|
+
* and `market-context-for-icp` (Phase 4.1);
|
|
33
|
+
* - the market generation CLI (`wildo market generate`) which
|
|
34
|
+
* concatenates the block with a `MarketMessageTemplate.promptTemplate`
|
|
35
|
+
* before sending to the LLM (Phase 4.2).
|
|
36
|
+
*
|
|
37
|
+
* **Pure function — no I/O, no DI, no runtime registry access, no
|
|
38
|
+
* mutation of the input snapshot.** The same `(snapshot, intent)`
|
|
39
|
+
* input always renders the same output (deterministic section order,
|
|
40
|
+
* deterministic ICP / benefit ordering by ref). This keeps the block
|
|
41
|
+
* trivial to snapshot-test and trivial to diff between snapshot
|
|
42
|
+
* versions.
|
|
43
|
+
*
|
|
44
|
+
* **English-only by contract (D15 / §12).** When `outputLanguage` is
|
|
45
|
+
* provided, the builder appends an "Output language" instruction line
|
|
46
|
+
* for the LLM, but does NOT translate any of the content above it.
|
|
47
|
+
* Translation happens at LLM-output time, never inside the spec.
|
|
48
|
+
*
|
|
49
|
+
* **Intent kinds:**
|
|
50
|
+
* - `{ kind: 'feature', featureRef }` — answers "I'm editing this
|
|
51
|
+
* feature, what is its market context?". Surfaces every benefit
|
|
52
|
+
* whose `deliveredByFeatureRefs[]` contains `featureRef`, the
|
|
53
|
+
* ICPs those benefits matter to, and the anti-target ICPs that
|
|
54
|
+
* would be repelled by them.
|
|
55
|
+
* - `{ kind: 'icp', icpRef }` — answers "I'm writing copy for this
|
|
56
|
+
* ICP, what's their world?". Surfaces the ICP's pains/gains/jobs,
|
|
57
|
+
* the benefits whose `importanceByICP[]` weights them at >= 5,
|
|
58
|
+
* and their preferred voice.
|
|
59
|
+
*
|
|
60
|
+
* **Section order (load-bearing — consumers may rely on it):**
|
|
61
|
+
* 1. `## Market context` header (with intent line)
|
|
62
|
+
* 2. `### Category`
|
|
63
|
+
* 3. `### Benefits in scope`
|
|
64
|
+
* 4. `### Most-affected ICPs`
|
|
65
|
+
* 5. `### Anti-target ICPs (do not pitch)`
|
|
66
|
+
* 6. `### Tone of voice`
|
|
67
|
+
* 7. `### Open questions / low-confidence entries` (skipped if empty)
|
|
68
|
+
* 8. `### Output language` (only when `outputLanguage` is set)
|
|
69
|
+
*
|
|
70
|
+
* Empty sections are kept (with an explicit `_(none)_` line) for
|
|
71
|
+
* sections 2–6 so the LLM sees the absence rather than silently
|
|
72
|
+
* inferring it. Section 7 is the lone exception — empty
|
|
73
|
+
* "low-confidence" lists carry no signal and are dropped.
|
|
74
|
+
*/
|
|
75
|
+
export interface MarketContextBlockInput {
|
|
76
|
+
/** Validated `MarketSnapshot`. Caller is responsible for running
|
|
77
|
+
* `validateMarketSnapshot` first; this builder trusts the input. */
|
|
78
|
+
snapshot: MarketSnapshot;
|
|
79
|
+
intent:
|
|
80
|
+
| { kind: 'feature'; featureRef: string }
|
|
81
|
+
| { kind: 'icp'; icpRef: string };
|
|
82
|
+
/** Optional BCP-47 tag (e.g. `'fr'`, `'pt-BR'`). When set, the
|
|
83
|
+
* builder appends an "Output language" instruction; never
|
|
84
|
+
* translates the body. */
|
|
85
|
+
outputLanguage?: string;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Trace of the entities the builder considered. Useful for the CLI's
|
|
90
|
+
* `--explain` mode and for unit tests that assert "the builder
|
|
91
|
+
* picked the right ICP" without parsing prose.
|
|
92
|
+
*
|
|
93
|
+
* **Schema contract.** This interface is intentionally kept
|
|
94
|
+
* structurally compatible with the public `MarketContextBlockTraceSchema`
|
|
95
|
+
* contract exported by `@wildo-ai/saas-specifications`
|
|
96
|
+
* — the Phase-4.2 market generation CLI parses the companion HTTP
|
|
97
|
+
* response against that Zod schema. Any drift between this
|
|
98
|
+
* interface and that schema must be reflected on **both** sides
|
|
99
|
+
* (the schema is the cross-process contract; this interface is the
|
|
100
|
+
* local renderer typing).
|
|
101
|
+
*/
|
|
102
|
+
export interface MarketContextBlockTrace {
|
|
103
|
+
/** Refs of every ICP whose section was rendered. Order matches
|
|
104
|
+
* the rendered output: feature intent → score-desc / priority /
|
|
105
|
+
* ref; icp intent → single requested ref or empty. */
|
|
106
|
+
icpsConsidered: string[];
|
|
107
|
+
/** Ordered (by ref) refs of every benefit whose section was rendered. */
|
|
108
|
+
benefitsConsidered: string[];
|
|
109
|
+
/** Ref of the tone of voice whose do/don't were rendered, or `null`. */
|
|
110
|
+
voiceUsed: string | null;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export interface MarketContextBlockResult {
|
|
114
|
+
/** English markdown prose, ready to concatenate with a template. */
|
|
115
|
+
block: string;
|
|
116
|
+
trace: MarketContextBlockTrace;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const ICP_PRIORITY_RANK: Record<ICPPriority, number> = {
|
|
120
|
+
[ICPPriority.CORE]: 0,
|
|
121
|
+
[ICPPriority.EXPANSION]: 1,
|
|
122
|
+
[ICPPriority.EXPLORATORY]: 2,
|
|
123
|
+
[ICPPriority.DEFERRED]: 3,
|
|
124
|
+
[ICPPriority.ANTI_TARGET]: 4,
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
/** Per-ICP fitness threshold for the `icp` intent's "Benefits in scope"
|
|
128
|
+
* section. Benefits with `importanceByICP[icp].weight >= 5` are
|
|
129
|
+
* considered relevant; below 5 the benefit is "noise" for that ICP. */
|
|
130
|
+
const ICP_BENEFIT_RELEVANCE_THRESHOLD = 5;
|
|
131
|
+
|
|
132
|
+
/** Maximum number of "Most-affected ICPs" lines rendered for the
|
|
133
|
+
* `feature` intent. Plan §10.2 caps at 3: the prompt should
|
|
134
|
+
* surface the *primary* audiences for a feature edit, not enumerate
|
|
135
|
+
* every ICP that mentioned it. The cap also keeps prompts short for
|
|
136
|
+
* snapshots with dozens of ICPs. */
|
|
137
|
+
const MAX_AFFECTED_ICPS_RENDERED = 3;
|
|
138
|
+
|
|
139
|
+
/** Defensive cap on the `outputLanguage` value rendered into the
|
|
140
|
+
* prompt. BCP-47 language tags are short by spec (the longest
|
|
141
|
+
* registered tag is well under 35 chars); a value longer than this
|
|
142
|
+
* is a misuse — most likely a caller pasted a paragraph instead of
|
|
143
|
+
* a tag. We refuse rather than silently embed garbage in the LLM
|
|
144
|
+
* prompt. The companion handlers also validate at the request
|
|
145
|
+
* boundary; this is a defense-in-depth guard for direct callers. */
|
|
146
|
+
const MAX_OUTPUT_LANGUAGE_LENGTH = 64;
|
|
147
|
+
|
|
148
|
+
export function buildMarketContextBlock(
|
|
149
|
+
input: MarketContextBlockInput,
|
|
150
|
+
): MarketContextBlockResult {
|
|
151
|
+
const { snapshot, intent, outputLanguage } = input;
|
|
152
|
+
|
|
153
|
+
const icpsByRef = new Map(snapshot.icps.map(icp => [icp.ref, icp] as const));
|
|
154
|
+
const benefitsByRef = new Map(snapshot.benefits.map(b => [b.ref, b] as const));
|
|
155
|
+
const voicesByRef = new Map(snapshot.tonesOfVoice.map(v => [v.ref, v] as const));
|
|
156
|
+
|
|
157
|
+
const benefitsInScope = collectBenefitsInScope(snapshot, intent);
|
|
158
|
+
const affectedIcps = collectAffectedIcps(intent, benefitsInScope, icpsByRef);
|
|
159
|
+
const antiTargetIcps = snapshot.icps
|
|
160
|
+
.filter(icp => icp.priority === ICPPriority.ANTI_TARGET)
|
|
161
|
+
.slice()
|
|
162
|
+
.sort(compareByRef);
|
|
163
|
+
|
|
164
|
+
const voice = pickPreferredVoice({
|
|
165
|
+
intent,
|
|
166
|
+
icpsByRef,
|
|
167
|
+
affectedIcps,
|
|
168
|
+
voicesByRef,
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
const lowConfidenceEntries = collectLowConfidenceEntries({
|
|
172
|
+
intent,
|
|
173
|
+
snapshot,
|
|
174
|
+
benefitsInScope,
|
|
175
|
+
affectedIcps,
|
|
176
|
+
});
|
|
177
|
+
|
|
178
|
+
const lines: string[] = [];
|
|
179
|
+
|
|
180
|
+
lines.push(renderHeader(intent));
|
|
181
|
+
lines.push('');
|
|
182
|
+
lines.push(renderCategorySection(snapshot));
|
|
183
|
+
lines.push('');
|
|
184
|
+
lines.push(renderBenefitsSection(benefitsInScope));
|
|
185
|
+
lines.push('');
|
|
186
|
+
lines.push(renderAffectedIcpsSection(affectedIcps, intent, benefitsInScope));
|
|
187
|
+
lines.push('');
|
|
188
|
+
lines.push(renderAntiTargetSection(antiTargetIcps));
|
|
189
|
+
lines.push('');
|
|
190
|
+
lines.push(renderVoiceSection(voice));
|
|
191
|
+
|
|
192
|
+
if (lowConfidenceEntries.length > 0) {
|
|
193
|
+
lines.push('');
|
|
194
|
+
lines.push(renderLowConfidenceSection(lowConfidenceEntries));
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
const normalizedOutputLanguage = normalizeOutputLanguage(outputLanguage);
|
|
198
|
+
if (normalizedOutputLanguage) {
|
|
199
|
+
lines.push('');
|
|
200
|
+
lines.push(renderOutputLanguageSection(normalizedOutputLanguage));
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
return {
|
|
204
|
+
block: lines.join('\n'),
|
|
205
|
+
trace: {
|
|
206
|
+
icpsConsidered: affectedIcps.map(icp => icp.ref),
|
|
207
|
+
benefitsConsidered: benefitsInScope.map(b => b.ref),
|
|
208
|
+
voiceUsed: voice?.ref ?? null,
|
|
209
|
+
},
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
// ---------------------------------------------------------------------------
|
|
214
|
+
// Collection helpers
|
|
215
|
+
// ---------------------------------------------------------------------------
|
|
216
|
+
|
|
217
|
+
function collectBenefitsInScope(
|
|
218
|
+
snapshot: MarketSnapshot,
|
|
219
|
+
intent: MarketContextBlockInput['intent'],
|
|
220
|
+
): FeatureBenefitConfig[] {
|
|
221
|
+
if (intent.kind === 'feature') {
|
|
222
|
+
return snapshot.benefits
|
|
223
|
+
.filter(b => b.deliveredByFeatureRefs.includes(intent.featureRef))
|
|
224
|
+
.slice()
|
|
225
|
+
.sort(compareByRef);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
return snapshot.benefits
|
|
229
|
+
.filter(b =>
|
|
230
|
+
b.importanceByICP.some(
|
|
231
|
+
imp =>
|
|
232
|
+
imp.icpRef === intent.icpRef &&
|
|
233
|
+
imp.weight >= ICP_BENEFIT_RELEVANCE_THRESHOLD,
|
|
234
|
+
),
|
|
235
|
+
)
|
|
236
|
+
.slice()
|
|
237
|
+
.sort(compareByRef);
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Per-ICP score for the `feature` intent's `### Most-affected ICPs`
|
|
242
|
+
* ranking. Plan §10.2 calls for `weight × pain/gain degree`. Concretely:
|
|
243
|
+
*
|
|
244
|
+
* score(icp) = max over benefits-in-scope of (
|
|
245
|
+
* importanceByICP[icp].weight × max(degree across that benefit's
|
|
246
|
+
* relieves[] / creates[] / advances[] edges)
|
|
247
|
+
* )
|
|
248
|
+
*
|
|
249
|
+
* **Why max-of-max instead of a sum.** A benefit's degree edges are
|
|
250
|
+
* authored as "this benefit relieves pain X to degree 9" — they
|
|
251
|
+
* describe the **strength of one outcome**, not a list of outcomes
|
|
252
|
+
* to add up. Summing across edges would over-weight benefits with
|
|
253
|
+
* many shallow edges; summing across benefits would over-weight ICPs
|
|
254
|
+
* that appear on lots of mid-importance benefits. The signal we want
|
|
255
|
+
* for "most-affected ICPs" is "what is the strongest claim this
|
|
256
|
+
* feature lets us make for this ICP", which is a max-of-max.
|
|
257
|
+
*
|
|
258
|
+
* **Tie-breaks are deterministic** (rank → ref) so the rendered
|
|
259
|
+
* output is snapshot-stable.
|
|
260
|
+
*/
|
|
261
|
+
function scoreIcpForFeatureIntent(
|
|
262
|
+
icpRef: string,
|
|
263
|
+
benefitsInScope: FeatureBenefitConfig[],
|
|
264
|
+
): number {
|
|
265
|
+
let best = 0;
|
|
266
|
+
for (const benefit of benefitsInScope) {
|
|
267
|
+
const weight = benefit.importanceByICP.find(imp => imp.icpRef === icpRef)?.weight;
|
|
268
|
+
if (weight === undefined || weight <= 0) continue;
|
|
269
|
+
let bestDegree = 0;
|
|
270
|
+
for (const edge of benefit.relieves) bestDegree = Math.max(bestDegree, edge.degree);
|
|
271
|
+
for (const edge of benefit.creates) bestDegree = Math.max(bestDegree, edge.degree);
|
|
272
|
+
for (const edge of benefit.advances) bestDegree = Math.max(bestDegree, edge.degree);
|
|
273
|
+
// Benefits with no degree edges still carry weight signal — use 1
|
|
274
|
+
// as a neutral multiplier so a weight-only ranking still differentiates.
|
|
275
|
+
const benefitScore = weight * (bestDegree > 0 ? bestDegree : 1);
|
|
276
|
+
if (benefitScore > best) best = benefitScore;
|
|
277
|
+
}
|
|
278
|
+
return best;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
function collectAffectedIcps(
|
|
282
|
+
intent: MarketContextBlockInput['intent'],
|
|
283
|
+
benefitsInScope: FeatureBenefitConfig[],
|
|
284
|
+
icpsByRef: Map<string, MarketICPConfig>,
|
|
285
|
+
): MarketICPConfig[] {
|
|
286
|
+
if (intent.kind === 'icp') {
|
|
287
|
+
const icp = icpsByRef.get(intent.icpRef);
|
|
288
|
+
return icp ? [icp] : [];
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
const refs = new Set<string>();
|
|
292
|
+
for (const benefit of benefitsInScope) {
|
|
293
|
+
for (const imp of benefit.importanceByICP) {
|
|
294
|
+
refs.add(imp.icpRef);
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
type ScoredIcp = { icp: MarketICPConfig; score: number };
|
|
299
|
+
const scored: ScoredIcp[] = [];
|
|
300
|
+
for (const ref of refs) {
|
|
301
|
+
const icp = icpsByRef.get(ref);
|
|
302
|
+
if (!icp || icp.priority === ICPPriority.ANTI_TARGET) continue;
|
|
303
|
+
scored.push({ icp, score: scoreIcpForFeatureIntent(ref, benefitsInScope) });
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
// Primary sort: weighted score (descending). Ties: priority rank
|
|
307
|
+
// (CORE before EXPANSION before lower priorities). Final tie-break:
|
|
308
|
+
// ref (alphabetical) for snapshot-stable output.
|
|
309
|
+
scored.sort((a, b) => {
|
|
310
|
+
if (a.score !== b.score) return b.score - a.score;
|
|
311
|
+
const rankDelta = ICP_PRIORITY_RANK[a.icp.priority] - ICP_PRIORITY_RANK[b.icp.priority];
|
|
312
|
+
if (rankDelta !== 0) return rankDelta;
|
|
313
|
+
return compareByRef(a.icp, b.icp);
|
|
314
|
+
});
|
|
315
|
+
|
|
316
|
+
return scored.slice(0, MAX_AFFECTED_ICPS_RENDERED).map(entry => entry.icp);
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
function pickPreferredVoice(params: {
|
|
320
|
+
intent: MarketContextBlockInput['intent'];
|
|
321
|
+
icpsByRef: Map<string, MarketICPConfig>;
|
|
322
|
+
affectedIcps: MarketICPConfig[];
|
|
323
|
+
voicesByRef: Map<string, ToneOfVoiceConfig>;
|
|
324
|
+
}): ToneOfVoiceConfig | null {
|
|
325
|
+
const { intent, icpsByRef, affectedIcps, voicesByRef } = params;
|
|
326
|
+
|
|
327
|
+
if (intent.kind === 'icp') {
|
|
328
|
+
const icp = icpsByRef.get(intent.icpRef);
|
|
329
|
+
if (icp?.preferredVoiceRef) {
|
|
330
|
+
const voice = voicesByRef.get(icp.preferredVoiceRef);
|
|
331
|
+
if (voice) return voice;
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
for (const icp of affectedIcps) {
|
|
336
|
+
if (icp.preferredVoiceRef) {
|
|
337
|
+
const voice = voicesByRef.get(icp.preferredVoiceRef);
|
|
338
|
+
if (voice) return voice;
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
return null;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
interface LowConfidenceEntry {
|
|
346
|
+
/** Dotted path inside the snapshot. */
|
|
347
|
+
path: string;
|
|
348
|
+
/** Display name of the entity (best-effort: `name` if present, else `ref`). */
|
|
349
|
+
label: string;
|
|
350
|
+
notes?: string;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
function collectLowConfidenceEntries(params: {
|
|
354
|
+
intent: MarketContextBlockInput['intent'];
|
|
355
|
+
snapshot: MarketSnapshot;
|
|
356
|
+
benefitsInScope: FeatureBenefitConfig[];
|
|
357
|
+
affectedIcps: MarketICPConfig[];
|
|
358
|
+
}): LowConfidenceEntry[] {
|
|
359
|
+
const { intent, snapshot, benefitsInScope, affectedIcps } = params;
|
|
360
|
+
const entries: LowConfidenceEntry[] = [];
|
|
361
|
+
|
|
362
|
+
if (isLowConfidence(snapshot.category.authored)) {
|
|
363
|
+
entries.push({
|
|
364
|
+
path: 'category',
|
|
365
|
+
label: snapshot.category.name,
|
|
366
|
+
notes: snapshot.category.authored?.notes,
|
|
367
|
+
});
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
for (const icp of affectedIcps) {
|
|
371
|
+
if (isLowConfidence(icp.authored)) {
|
|
372
|
+
entries.push({
|
|
373
|
+
path: `icps[${snapshot.icps.indexOf(icp)}]`,
|
|
374
|
+
label: icp.name,
|
|
375
|
+
notes: icp.authored?.notes,
|
|
376
|
+
});
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
for (const benefit of benefitsInScope) {
|
|
381
|
+
if (isLowConfidence(benefit.authored)) {
|
|
382
|
+
entries.push({
|
|
383
|
+
path: `benefits[${snapshot.benefits.indexOf(benefit)}]`,
|
|
384
|
+
label: benefit.claim,
|
|
385
|
+
notes: benefit.authored?.notes,
|
|
386
|
+
});
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
// Personas: surface LOW-confidence personas whose `belongsToIcpRefs[]`
|
|
391
|
+
// intersects the **affected ICPs** for either intent kind. Under
|
|
392
|
+
// `icp` intent this is the requested ICP itself; under `feature`
|
|
393
|
+
// intent it's any ICP that the renderer surfaced under
|
|
394
|
+
// "Most-affected ICPs". Restricting to affected ICPs keeps the
|
|
395
|
+
// section signal-dense — we don't dump every LOW persona in the
|
|
396
|
+
// snapshot, only the ones the LLM is about to write copy for.
|
|
397
|
+
const affectedIcpRefs = new Set(affectedIcps.map(i => i.ref));
|
|
398
|
+
if (affectedIcpRefs.size > 0) {
|
|
399
|
+
for (const persona of snapshot.personas) {
|
|
400
|
+
if (!isLowConfidence(persona.authored)) continue;
|
|
401
|
+
if (!persona.belongsToIcpRefs.some(ref => affectedIcpRefs.has(ref))) continue;
|
|
402
|
+
entries.push({
|
|
403
|
+
path: `personas[${snapshot.personas.indexOf(persona)}]`,
|
|
404
|
+
label: persona.name,
|
|
405
|
+
notes: persona.authored?.notes,
|
|
406
|
+
});
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
return entries;
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
function isLowConfidence(authored: MarketAuthoredMetadata | undefined): boolean {
|
|
414
|
+
return authored?.confidence === AuthoredConfidence.LOW;
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
function compareByRef<T extends { ref: string }>(a: T, b: T): number {
|
|
418
|
+
return a.ref.localeCompare(b.ref);
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
// ---------------------------------------------------------------------------
|
|
422
|
+
// Render helpers
|
|
423
|
+
// ---------------------------------------------------------------------------
|
|
424
|
+
|
|
425
|
+
function renderHeader(intent: MarketContextBlockInput['intent']): string {
|
|
426
|
+
const intentLine =
|
|
427
|
+
intent.kind === 'feature'
|
|
428
|
+
? `(intent: feature \`${intent.featureRef}\`)`
|
|
429
|
+
: `(intent: icp \`${intent.icpRef}\`)`;
|
|
430
|
+
return `## Market context ${intentLine}`;
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
function renderCategorySection(snapshot: MarketSnapshot): string {
|
|
434
|
+
const { name, definition } = snapshot.category;
|
|
435
|
+
return [
|
|
436
|
+
'### Category',
|
|
437
|
+
`- **Name:** ${name}`,
|
|
438
|
+
`- **Definition:** ${definition}`,
|
|
439
|
+
].join('\n');
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
function renderBenefitsSection(benefits: FeatureBenefitConfig[]): string {
|
|
443
|
+
const lines = ['### Benefits in scope'];
|
|
444
|
+
if (benefits.length === 0) {
|
|
445
|
+
lines.push('_(none)_');
|
|
446
|
+
return lines.join('\n');
|
|
447
|
+
}
|
|
448
|
+
for (const benefit of benefits) {
|
|
449
|
+
const edges: string[] = [];
|
|
450
|
+
for (const e of benefit.relieves) {
|
|
451
|
+
edges.push(`relieves \`${e.painRef}\` (degree ${e.degree})`);
|
|
452
|
+
}
|
|
453
|
+
for (const e of benefit.creates) {
|
|
454
|
+
edges.push(`creates \`${e.gainRef}\` (degree ${e.degree})`);
|
|
455
|
+
}
|
|
456
|
+
for (const e of benefit.advances) {
|
|
457
|
+
edges.push(`advances \`${e.jobRef}\` (degree ${e.degree})`);
|
|
458
|
+
}
|
|
459
|
+
const edgeSummary = edges.length > 0 ? ` — ${edges.join('; ')}` : '';
|
|
460
|
+
lines.push(`- **${benefit.claim}** (\`${benefit.ref}\`, role ${benefit.role})${edgeSummary}`);
|
|
461
|
+
}
|
|
462
|
+
return lines.join('\n');
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
function renderAffectedIcpsSection(
|
|
466
|
+
icps: MarketICPConfig[],
|
|
467
|
+
intent: MarketContextBlockInput['intent'],
|
|
468
|
+
benefitsInScope: FeatureBenefitConfig[],
|
|
469
|
+
): string {
|
|
470
|
+
const heading =
|
|
471
|
+
intent.kind === 'feature'
|
|
472
|
+
? '### Most-affected ICPs'
|
|
473
|
+
: '### ICP profile';
|
|
474
|
+
const lines = [heading];
|
|
475
|
+
if (icps.length === 0) {
|
|
476
|
+
lines.push('_(none)_');
|
|
477
|
+
return lines.join('\n');
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
for (const icp of icps) {
|
|
481
|
+
const relevantImportance = benefitsInScope
|
|
482
|
+
.flatMap(b => b.importanceByICP)
|
|
483
|
+
.filter(imp => imp.icpRef === icp.ref);
|
|
484
|
+
const kanoSummary =
|
|
485
|
+
relevantImportance.length > 0
|
|
486
|
+
? ` — kano: ${relevantImportance
|
|
487
|
+
.map(i => `${i.kanoCategory}@${i.weight}`)
|
|
488
|
+
.join(', ')}`
|
|
489
|
+
: '';
|
|
490
|
+
lines.push(
|
|
491
|
+
`- **${icp.name}** (\`${icp.ref}\`, priority ${icp.priority}, archetype ${icp.archetype})${kanoSummary}`,
|
|
492
|
+
);
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
return lines.join('\n');
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
function renderAntiTargetSection(icps: MarketICPConfig[]): string {
|
|
499
|
+
const lines = ['### Anti-target ICPs (do not pitch)'];
|
|
500
|
+
if (icps.length === 0) {
|
|
501
|
+
lines.push('_(none)_');
|
|
502
|
+
return lines.join('\n');
|
|
503
|
+
}
|
|
504
|
+
for (const icp of icps) {
|
|
505
|
+
lines.push(`- **${icp.name}** (\`${icp.ref}\`, archetype ${icp.archetype})`);
|
|
506
|
+
}
|
|
507
|
+
return lines.join('\n');
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
function renderVoiceSection(voice: ToneOfVoiceConfig | null): string {
|
|
511
|
+
const lines = ['### Tone of voice'];
|
|
512
|
+
if (!voice) {
|
|
513
|
+
lines.push('_(none — fall back to neutral)_');
|
|
514
|
+
return lines.join('\n');
|
|
515
|
+
}
|
|
516
|
+
lines.push(`- **${voice.name}** (\`${voice.ref}\`) — ${voice.description}`);
|
|
517
|
+
lines.push(`- **address:** ${voice.address}`);
|
|
518
|
+
lines.push(`- **do:** ${voice.doExamples.map(s => `"${s}"`).join('; ')}`);
|
|
519
|
+
lines.push(`- **don't:** ${voice.dontExamples.map(s => `"${s}"`).join('; ')}`);
|
|
520
|
+
return lines.join('\n');
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
function renderLowConfidenceSection(entries: LowConfidenceEntry[]): string {
|
|
524
|
+
const lines = ['### Open questions / low-confidence entries'];
|
|
525
|
+
for (const entry of entries) {
|
|
526
|
+
const noteSuffix = entry.notes ? ` — ${entry.notes}` : '';
|
|
527
|
+
lines.push(`- \`${entry.path}\` **${entry.label}**${noteSuffix}`);
|
|
528
|
+
}
|
|
529
|
+
return lines.join('\n');
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
/**
|
|
533
|
+
* Trim and validate an `outputLanguage` value before it lands inside
|
|
534
|
+
* the prompt. Returns `undefined` for missing / empty / whitespace-only
|
|
535
|
+
* inputs (so the section is skipped entirely). Throws for values
|
|
536
|
+
* longer than {@link MAX_OUTPUT_LANGUAGE_LENGTH} — that's a caller
|
|
537
|
+
* misuse (e.g. pasting a paragraph instead of a tag).
|
|
538
|
+
*/
|
|
539
|
+
function normalizeOutputLanguage(value: string | undefined): string | undefined {
|
|
540
|
+
if (value === undefined) return undefined;
|
|
541
|
+
const trimmed = value.trim();
|
|
542
|
+
if (trimmed.length === 0) return undefined;
|
|
543
|
+
if (trimmed.length > MAX_OUTPUT_LANGUAGE_LENGTH) {
|
|
544
|
+
throw new Error(
|
|
545
|
+
`buildMarketContextBlock: \`outputLanguage\` is ${trimmed.length} chars long `
|
|
546
|
+
+ `(max ${MAX_OUTPUT_LANGUAGE_LENGTH}). Pass a BCP-47 tag (e.g. \`'fr'\`, \`'pt-BR'\`), `
|
|
547
|
+
+ `not a sentence — translation prose belongs in the LLM output, not the tag.`,
|
|
548
|
+
);
|
|
549
|
+
}
|
|
550
|
+
return trimmed;
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
function renderOutputLanguageSection(outputLanguage: string): string {
|
|
554
|
+
return [
|
|
555
|
+
'### Output language',
|
|
556
|
+
`Produce the final output in \`${outputLanguage}\`. The market context above is English on purpose — do not translate it; translate at output time only.`,
|
|
557
|
+
].join('\n');
|
|
558
|
+
}
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
## Behavior definitions (source)
|
|
562
|
+
|
|
563
|
+
`market-context-for-feature` and `market-context-for-icp`. Both
|
|
564
|
+
served by the `'specifications'` route, both `'market'` category,
|
|
565
|
+
both `materializationKind: 'json-snapshot'`. The CLI side issues
|
|
566
|
+
a standard `companionPost` request to either behavior id.
|
|
567
|
+
|
|
568
|
+
## Import Origins
|
|
569
|
+
|
|
570
|
+
- `@wildo-ai/dev-companion`
|
|
571
|
+
|
|
572
|
+
## Source Excerpts
|
|
573
|
+
|
|
574
|
+
### Origin Package: `@wildo-ai/dev-companion`
|
|
575
|
+
|
|
576
|
+
```typescript
|
|
577
|
+
*/
|
|
578
|
+
'market-context-for-feature': {
|
|
579
|
+
behaviorId: 'market-context-for-feature',
|
|
580
|
+
description:
|
|
581
|
+
'Render an English market-context block for a feature ref — benefits in scope, '
|
|
582
|
+
+ 'most-affected ICPs, anti-targets, preferred voice. Consumed by the dev companion '
|
|
583
|
+
+ '"edit feature X" prompt enrichment and by the market generation CLI (Phase 4.2).',
|
|
584
|
+
category: 'market',
|
|
585
|
+
supportedServiceKinds: ['backend', 'frontend'],
|
|
586
|
+
routingByServiceKind: {
|
|
587
|
+
backend: {
|
|
588
|
+
target: 'specifications',
|
|
589
|
+
},
|
|
590
|
+
frontend: {
|
|
591
|
+
target: 'specifications',
|
|
592
|
+
},
|
|
593
|
+
},
|
|
594
|
+
execution: {
|
|
595
|
+
...SHARED_EXECUTION_BOUNDARY,
|
|
596
|
+
materializationKind: 'json-snapshot',
|
|
597
|
+
},
|
|
598
|
+
},
|
|
599
|
+
'market-context-for-icp': {
|
|
600
|
+
behaviorId: 'market-context-for-icp',
|
|
601
|
+
description:
|
|
602
|
+
'Render an English market-context block for an ICP ref — relevant benefits, ICP profile, '
|
|
603
|
+
+ 'anti-targets, preferred voice. Consumed by the market generation CLI when generating '
|
|
604
|
+
+ 'per-ICP outputs (landing pages, emails, objection responses).',
|
|
605
|
+
category: 'market',
|
|
606
|
+
supportedServiceKinds: ['backend', 'frontend'],
|
|
607
|
+
routingByServiceKind: {
|
|
608
|
+
backend: {
|
|
609
|
+
target: 'specifications',
|
|
610
|
+
},
|
|
611
|
+
frontend: {
|
|
612
|
+
target: 'specifications',
|
|
613
|
+
},
|
|
614
|
+
},
|
|
615
|
+
execution: {
|
|
616
|
+
...SHARED_EXECUTION_BOUNDARY,
|
|
617
|
+
materializationKind: 'json-snapshot',
|
|
618
|
+
},
|
|
619
|
+
},
|
|
620
|
+
/**
|
|
621
|
+
* Phase-4.2 market generation behavior. Materializes the **fully rendered
|
|
622
|
+
* prompt** for one `MarketMessageTemplate` ref + caller-supplied input
|
|
623
|
+
* refs (icp / feature / benefit / channel / objection / outputLanguage).
|
|
624
|
+
* The subprocess owns snapshot resolution + validation, template lookup,
|
|
625
|
+
* `requiredInputs` enforcement, context-block rendering, and Mustache
|
|
626
|
+
* substitution; the parent process consumes only the final prompt
|
|
627
|
+
* string before handing it to `AgentsBackendService.invokeAgent(...)`.
|
|
628
|
+
*
|
|
629
|
+
* The handler intentionally does NOT call the LLM itself — keeping the
|
|
630
|
+
* subprocess pure-and-deterministic preserves the "snapshot resolution
|
|
631
|
+
* happens in a child process, LLM happens in the parent" boundary
|
|
632
|
+
* established in Phase 4.1.
|
|
633
|
+
*/
|
|
634
|
+
'market-render-prompt': {
|
|
635
|
+
behaviorId: 'market-render-prompt',
|
|
636
|
+
description:
|
|
637
|
+
'Render the full market generation prompt (English market-context block + Mustache-substituted '
|
|
638
|
+
+ 'message template body) for one MarketMessageTemplate ref. Consumed by the dev-companion '
|
|
639
|
+
+ '`/api/companion/market/generate` route, which feeds the prompt to AgentsBackendService.',
|
|
640
|
+
category: 'market',
|
|
641
|
+
supportedServiceKinds: ['backend', 'frontend'],
|
|
642
|
+
routingByServiceKind: {
|
|
643
|
+
backend: {
|
|
644
|
+
target: 'specifications',
|
|
645
|
+
},
|
|
646
|
+
frontend: {
|
|
647
|
+
target: 'specifications',
|
|
648
|
+
},
|
|
649
|
+
},
|
|
650
|
+
execution: {
|
|
651
|
+
...SHARED_EXECUTION_BOUNDARY,
|
|
652
|
+
materializationKind: 'json-snapshot',
|
|
653
|
+
},
|
|
654
|
+
},
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
## Behavior handlers (source)
|
|
658
|
+
|
|
659
|
+
The handler for each behavior parses a tiny request payload, resolves
|
|
660
|
+
the authored `MarketSnapshot` via `resolveSpecificationsCompanionExports`,
|
|
661
|
+
and defers to the pure `buildMarketContextBlock`. The handlers throw
|
|
662
|
+
descriptive errors when the payload is malformed or when the consuming
|
|
663
|
+
specifications package does not export a `marketSpecification`.
|
|
664
|
+
|
|
665
|
+
## Import Origins
|
|
666
|
+
|
|
667
|
+
- `@wildo-ai/dev-companion`
|
|
668
|
+
|
|
669
|
+
## Source Excerpts
|
|
670
|
+
|
|
671
|
+
### Origin Package: `@wildo-ai/dev-companion`
|
|
672
|
+
|
|
673
|
+
```typescript
|
|
674
|
+
*/
|
|
675
|
+
'market-context-for-feature': (input, context) => {
|
|
676
|
+
const { featureRef, outputLanguage } = parseMarketContextFeatureRequest(input);
|
|
677
|
+
const snapshot = resolveMarketSnapshot(context.moduleExports);
|
|
678
|
+
return buildMarketContextBlock({
|
|
679
|
+
snapshot,
|
|
680
|
+
intent: { kind: 'feature', featureRef },
|
|
681
|
+
outputLanguage,
|
|
682
|
+
});
|
|
683
|
+
},
|
|
684
|
+
'market-context-for-icp': (input, context) => {
|
|
685
|
+
const { icpRef, outputLanguage } = parseMarketContextIcpRequest(input);
|
|
686
|
+
const snapshot = resolveMarketSnapshot(context.moduleExports);
|
|
687
|
+
return buildMarketContextBlock({
|
|
688
|
+
snapshot,
|
|
689
|
+
intent: { kind: 'icp', icpRef },
|
|
690
|
+
outputLanguage,
|
|
691
|
+
});
|
|
692
|
+
},
|
|
693
|
+
/**
|
|
694
|
+
* Phase-4.2 market generation handler. Reuses the same snapshot
|
|
695
|
+
* resolver as the two `market-context-*` handlers (so validation
|
|
696
|
+
* runs once per snapshot identity, with shared WARN dedup) and
|
|
697
|
+
* defers prompt assembly to the pure `renderMarketPrompt(...)`.
|
|
698
|
+
*/
|
|
699
|
+
'market-render-prompt': (input, context) => {
|
|
700
|
+
const request = parseMarketRenderPromptRequest(input);
|
|
701
|
+
const snapshot = resolveMarketSnapshot(context.moduleExports);
|
|
702
|
+
return renderMarketPrompt({ snapshot, request });
|
|
703
|
+
},
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
## Companion-exports surface (source)
|
|
707
|
+
|
|
708
|
+
The dev companion resolves the snapshot through the standard
|
|
709
|
+
`SpecificationsCompanionExports.marketSpecification` slot. Apps wire
|
|
710
|
+
this slot in their `specifications/src/companion-exports.ts`.
|
|
711
|
+
|
|
712
|
+
## Import Origins
|
|
713
|
+
|
|
714
|
+
- `@wildo-ai/saas-specifications`
|
|
715
|
+
|
|
716
|
+
## Source Excerpts
|
|
717
|
+
|
|
718
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
719
|
+
|
|
720
|
+
```typescript
|
|
721
|
+
*
|
|
722
|
+
* Typed companion export surface: registries of resource specs, definitions, and view specs the dev companion materializes.
|
|
723
|
+
*/
|
|
724
|
+
export interface SpecificationsCompanionExports<
|
|
725
|
+
TResourceSpecifications = ResourceSpecification,
|
|
726
|
+
TBusinessSemanticsSnapshot = BusinessSemanticsSnapshot,
|
|
727
|
+
TFeatureSpecifications = FeatureSpecification,
|
|
728
|
+
TMilestoneSpecifications = MilestoneSpecification,
|
|
729
|
+
TProductSpecifications = ProductSpecification,
|
|
730
|
+
TRoleSpecifications = RoleSpecification,
|
|
731
|
+
TFrontendComponentSpecifications = FrontendComponentSpecification,
|
|
732
|
+
TCompositeViewSpecifications = CompositeViewSpecification,
|
|
733
|
+
TFullCustomViewSpecifications = FullCustomViewSpecification,
|
|
734
|
+
TFlowsActorsViewSpecifications = FlowsActorsViewSpecification,
|
|
735
|
+
TChartViewSpecifications = ChartViewSpecification,
|
|
736
|
+
TExecutionViewSpecifications = ExecutionViewSpecification,
|
|
737
|
+
TSystemEmailTemplateSpecifications = SystemEmailTemplateSpecification,
|
|
738
|
+
TOnboardingViewSpecifications = OnboardingViewSpecification,
|
|
739
|
+
TGuidanceFlowSpecifications = GuidanceFlowSpecification,
|
|
740
|
+
TDataSeedSpecifications = DataSeedSpecification,
|
|
741
|
+
TMarketSnapshot = MarketSnapshot,
|
|
742
|
+
TCatalogSpecifications = CatalogSpecifications,
|
|
743
|
+
// Appended LAST (not inserted mid-list): consumers pass these generics
|
|
744
|
+
// positionally (see the app companion-exports), so a new param must go at the
|
|
745
|
+
// end to avoid shifting existing ones onto the wrong types.
|
|
746
|
+
TSidebarSectionSpecifications = SidebarSectionSpecification,
|
|
747
|
+
TAssertionSpecifications = AssertionSpecificationSnapshot,
|
|
748
|
+
// ── app-creation meta-workflows C-4 definition families (U1–U4) — RESERVED SLOTS ──
|
|
749
|
+
// Four sibling `_core` families each register ONE companion-exports slot here,
|
|
750
|
+
// appended STRICTLY LAST in this FIXED order. Each session appends its generic
|
|
751
|
+
// param (below) AND its interface field (further down) AFTER the previous
|
|
752
|
+
// family's — NEVER re-order, NEVER insert mid-list. Consumers pass generics
|
|
753
|
+
// positionally, so re-ordering silently shifts every later app onto the wrong
|
|
754
|
+
// type. The reservation order (do not change):
|
|
755
|
+
// All four reserved families are now registered (U1–U4 done); the
|
|
756
|
+
// reserved-slots block below is fully filled and no further reservation
|
|
757
|
+
// follows. The final order (do not change):
|
|
758
|
+
// 1. vision (U1 — registered below)
|
|
759
|
+
// 2. requirements (U2 — registered below)
|
|
760
|
+
// 3. roadmap (U3 — registered below)
|
|
761
|
+
// 4. business-model-lite (U4 — registered below, LAST)
|
|
762
|
+
TVisionSnapshot = VisionSnapshot,
|
|
763
|
+
TRequirementsSnapshot = RequirementsSnapshot,
|
|
764
|
+
TRoadmapSnapshot = RoadmapSnapshot,
|
|
765
|
+
TBuildPlanTaskGraph = BuildPlanTaskGraph,
|
|
766
|
+
TPlacementPlan = PlacementPlan,
|
|
767
|
+
TDomainPlanOutputSet = DomainPlanOutputSet,
|
|
768
|
+
TBusinessModelLiteSnapshot = BusinessModelLiteSnapshot,
|
|
769
|
+
// Appended STRICTLY LAST (positional generics — never insert mid-list):
|
|
770
|
+
// the brand visual-identity definition family (`brand-brief`).
|
|
771
|
+
TBrandSnapshot = BrandSnapshot,
|
|
772
|
+
// Appended STRICTLY LAST: the expert-personas family (derived worker-persona
|
|
773
|
+
// charters — plural array, unlike the singleton snapshot families above).
|
|
774
|
+
TExpertPersonaCharters = ExpertPersonaCharter[],
|
|
775
|
+
// Appended STRICTLY LAST: accepted spec-first feature intent. This is
|
|
776
|
+
// deliberately distinct from `featureSpecifications`, whose entries already
|
|
777
|
+
// decorate runtime FeatureDefinitions and therefore represent a later stage.
|
|
778
|
+
TFeatureSpecificationDrafts = FeatureSpecificationDrafts,
|
|
779
|
+
// Appended STRICTLY LAST: accepted application compliance policy. The slot
|
|
780
|
+
// remains optional so applications that do not opt into `compliance-program`
|
|
781
|
+
// preserve their existing projection and family-head behavior.
|
|
782
|
+
TComplianceSpecification = AssuranceProgramSpecification,
|
|
783
|
+
// Appended STRICTLY LAST: the application's accepted public-document
|
|
784
|
+
// publication variants (`document-publication` family). Separate from
|
|
785
|
+
// `complianceSpecification` on purpose — see the field's JSDoc.
|
|
786
|
+
TDocumentPublicationSpecification = ApplicationDocumentPublicationSpecification,
|
|
787
|
+
// Appended STRICTLY LAST: accepted document facts that cannot be inferred
|
|
788
|
+
// from other semantic families. Raw decisions only; runtime grants,
|
|
789
|
+
// approvals and releases never enter companion exports.
|
|
790
|
+
TDocumentFactSpecification = ApplicationDocumentFactSpecification,
|
|
791
|
+
// Appended STRICTLY LAST: release-process selection is a separate accepted
|
|
792
|
+
// decision, never an implicit default of routing or document necessity.
|
|
793
|
+
TDocumentReleasePolicySpecification = ApplicationDocumentReleasePolicySpecification,
|
|
794
|
+
// Appended STRICTLY LAST: WHO else processes personal data, under what legal
|
|
795
|
+
// identity and where (issue #88). Optional, and the optionality is the design:
|
|
796
|
+
// a partial register is useful and its holes are REPORTED per provider against
|
|
797
|
+
// the application's configured set, rather than blocking anything.
|
|
798
|
+
TProcessorRegister = ApplicationProcessorRegister,
|
|
799
|
+
> {
|
|
800
|
+
resourceSpecifications: TResourceSpecifications;
|
|
801
|
+
applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
|
|
802
|
+
/**
|
|
803
|
+
* Feature overlays exposed to the dev companion.
|
|
804
|
+
*
|
|
805
|
+
* **Required** (promoted 2026-04-22, carryforward #5 of the
|
|
806
|
+
* `non-view-specification-coverage` plan). The engine ships 7 explicit
|
|
807
|
+
* `CoreFeature` overlays plus an `EngineCapability`-derived programmatic
|
|
808
|
+
* module via `engineFeatureSpecifications`, so apps always have
|
|
809
|
+
* something to expose. Apps with no app-level feature overlays should
|
|
810
|
+
* pass `engineFeatureSpecifications` directly; apps with overlays
|
|
811
|
+
* should merge their own bi-scoped map on top using the same
|
|
812
|
+
* `buildFeatureSpecificationMap(...)` factory used by Your Application.
|
|
813
|
+
*/
|
|
814
|
+
featureSpecifications: TFeatureSpecifications;
|
|
815
|
+
/**
|
|
816
|
+
* Milestone overlays exposed to the dev companion.
|
|
817
|
+
*
|
|
818
|
+
* **Required** (promoted 2026-04-22, carryforward #5). Engine ships
|
|
819
|
+
* zero milestone overlays today (apps own the catalog), but the
|
|
820
|
+
* required discipline forces apps to either pass an explicit
|
|
821
|
+
* `buildMilestoneSpecificationMap()` (empty or otherwise) or wire a
|
|
822
|
+
* real overlay registry — eliminating the silent "I forgot to wire
|
|
823
|
+
* this surface" failure mode the optional shape allowed.
|
|
824
|
+
*/
|
|
825
|
+
milestoneSpecifications: TMilestoneSpecifications;
|
|
826
|
+
/**
|
|
827
|
+
* Product overlays exposed to the dev companion.
|
|
828
|
+
*
|
|
829
|
+
* **Required** (promoted 2026-04-22, carryforward #5). Same rationale
|
|
830
|
+
* as `milestoneSpecifications` — engine ships zero today, but the
|
|
831
|
+
* required shape eliminates the silent-omission failure mode.
|
|
832
|
+
*/
|
|
833
|
+
productSpecifications: TProductSpecifications;
|
|
834
|
+
/**
|
|
835
|
+
* Role overlays exposed to the dev companion.
|
|
836
|
+
*
|
|
837
|
+
* **Required** (promoted 2026-04-22, carryforward #5). Engine ships
|
|
838
|
+
* 12 explicit core-role overlays via `engineRoleSpecifications` (one
|
|
839
|
+
* per `CORE_APP_ROLES.*` member), so apps always have something to
|
|
840
|
+
* expose. Apps with no app-level roles should pass
|
|
841
|
+
* `engineRoleSpecifications` directly.
|
|
842
|
+
*/
|
|
843
|
+
roleSpecifications: TRoleSpecifications;
|
|
844
|
+
frontendComponentSpecifications?: TFrontendComponentSpecifications;
|
|
845
|
+
compositeViewSpecifications?: TCompositeViewSpecifications;
|
|
846
|
+
fullCustomViewSpecifications?: TFullCustomViewSpecifications;
|
|
847
|
+
flowsActorsViewSpecifications?: TFlowsActorsViewSpecifications;
|
|
848
|
+
chartViewSpecifications?: TChartViewSpecifications;
|
|
849
|
+
executionViewSpecifications?: TExecutionViewSpecifications;
|
|
850
|
+
/**
|
|
851
|
+
* Sidebar-section overlays exposed to the dev companion. Optional: sidebar
|
|
852
|
+
* sections are structural app-shell config with no prose of their own; an app
|
|
853
|
+
* that wants grounded sidebar labels authors a
|
|
854
|
+
* `buildSidebarSectionSpecificationMap(...)` here, otherwise the family falls
|
|
855
|
+
* back to keys-only generation.
|
|
856
|
+
*/
|
|
857
|
+
sidebarSectionSpecifications?: TSidebarSectionSpecifications;
|
|
858
|
+
/**
|
|
859
|
+
* System-email template overlays exposed to the dev companion.
|
|
860
|
+
*
|
|
861
|
+
* **Required** because the engine ships 12 templates out of the box
|
|
862
|
+
* (`engineSystemEmailTemplateSpecifications`); apps therefore always have
|
|
863
|
+
* something to expose, and forgetting to wire this surface would silently
|
|
864
|
+
* lose the entire system-email companion family. Apps with no app-level
|
|
865
|
+
* templates should pass `engineSystemEmailTemplateSpecifications` directly.
|
|
866
|
+
*/
|
|
867
|
+
systemEmailTemplateSpecifications: TSystemEmailTemplateSpecifications;
|
|
868
|
+
/**
|
|
869
|
+
* Onboarding-view overlays exposed to the dev companion.
|
|
870
|
+
*
|
|
871
|
+
* **Required** (promoted 2026-04-22, carryforward #5). Engine ships
|
|
872
|
+
* zero onboarding views by default, but the required shape eliminates
|
|
873
|
+
* the silent-omission failure mode. Apps with no app-level onboarding
|
|
874
|
+
* views should pass an empty `buildOnboardingViewSpecificationMap()`
|
|
875
|
+
* rather than omitting the field.
|
|
876
|
+
*/
|
|
877
|
+
onboardingViewSpecifications: TOnboardingViewSpecifications;
|
|
878
|
+
/**
|
|
879
|
+
* Guidance-flow overlays exposed to the dev companion.
|
|
880
|
+
*
|
|
881
|
+
* **Required** (promoted 2026-04-22, carryforward #5). Same discipline
|
|
882
|
+
* as `onboardingViewSpecifications` — engine ships zero by default,
|
|
883
|
+
* but the required shape eliminates the silent-omission failure mode.
|
|
884
|
+
* Apps with no app-level guidance flows should pass an empty
|
|
885
|
+
* `buildGuidanceFlowSpecificationMap()` rather than omitting the field.
|
|
886
|
+
*/
|
|
887
|
+
guidanceFlowSpecifications: TGuidanceFlowSpecifications;
|
|
888
|
+
/**
|
|
889
|
+
* Data-seeding overlays exposed to the dev companion.
|
|
890
|
+
*
|
|
891
|
+
* **Optional** in Phase 1 because the engine ships zero seeds yet — the
|
|
892
|
+
* `DataSeedRegistry` and the dispatcher land in Phase 2. Authoring a seed
|
|
893
|
+
* spec without the runtime declaration is allowed (the spec slice is
|
|
894
|
+
* useful as design documentation on its own); authoring a runtime seed
|
|
895
|
+
* without a spec is also allowed (no companion grounding, dispatcher
|
|
896
|
+
* still runs it). Once Phase 2 ships engine seeds this field will be
|
|
897
|
+
* promoted to required, mirroring `systemEmailTemplateSpecifications`.
|
|
898
|
+
*
|
|
899
|
+
* Apps with no app-level seeds should pass an empty
|
|
900
|
+
* `buildDataSeedSpecificationMap()` rather than omitting the field once
|
|
901
|
+
* Phase 2 lands.
|
|
902
|
+
*/
|
|
903
|
+
dataSeedSpecifications?: TDataSeedSpecifications;
|
|
904
|
+
/**
|
|
905
|
+
* Application market specification — the English-authored marketing /
|
|
906
|
+
* positioning truth (category, ICPs, personas, jobs/pains/gains, tones
|
|
907
|
+
* of voice, benefits, positionings, message templates). Optional today
|
|
908
|
+
* because not every example app authors a market snapshot yet; once it
|
|
909
|
+
* graduates to required, app bootstraps should run
|
|
910
|
+
* `validateMarketSnapshot` on the value before wiring it here.
|
|
911
|
+
*
|
|
912
|
+
* Authored entirely in English. Geographic targeting (the only
|
|
913
|
+
* "localization" the slice models) lives inside
|
|
914
|
+
* `MarketICP.profile.geographies`.
|
|
915
|
+
*/
|
|
916
|
+
marketSpecification?: TMarketSnapshot;
|
|
917
|
+
/**
|
|
918
|
+
* Catalog specifications — declarations of EXTERNAL vocabularies the
|
|
919
|
+
* framework reasons about (Schema.org JSON-LD today; future:
|
|
920
|
+
* OpenAPI, RSS, JSON-Feed). Distinct from overlay specs above —
|
|
921
|
+
* overlay specs decorate registry entries (resources, features,
|
|
922
|
+
* views); catalog specs OWN the contract for an external
|
|
923
|
+
* vocabulary's per-entity shape (required / optional / deprecated
|
|
924
|
+
* field declarations).
|
|
925
|
+
*
|
|
926
|
+
* **Composition**: apps spread the engine catalog (e.g.
|
|
927
|
+
* `ENGINE_SCHEMA_ORG_CATALOG`) and append app-side extensions /
|
|
928
|
+
* overrides. The companion's catalog reconciliation runs against
|
|
929
|
+
* this merged surface — emission sites in `@wildo-ai/saas-website`
|
|
930
|
+
* sections (via `getStructuredData()`) are checked against the
|
|
931
|
+
* merged `schemaOrg` catalog, with warnings on missing required
|
|
932
|
+
* fields, deprecated-field usage, and (when wired) missing
|
|
933
|
+
* recommended optionals. Catalog overrides (app entry redefining
|
|
934
|
+
* an engine entry's `@type`) emit a `catalog-override` boot
|
|
935
|
+
* warning.
|
|
936
|
+
*
|
|
937
|
+
* **Optional** in v1 because not every app emits structured data
|
|
938
|
+
* yet. Apps wiring an engine catalog explicitly opt into
|
|
939
|
+
* companion reconciliation by populating the matching slot.
|
|
940
|
+
*/
|
|
941
|
+
catalogSpecifications?: TCatalogSpecifications;
|
|
942
|
+
/**
|
|
943
|
+
* Assertion surface — the authored layer of the dynamic Assertion
|
|
944
|
+
* Surface (app-creation meta-workflows, master plan S1): statements
|
|
945
|
+
* about the platform served via the companion `assertions-list` /
|
|
946
|
+
* `assertions-resolve` / `assertions-reconcile` behaviors, with
|
|
947
|
+
* status computed by reconcile rather than hand-maintained.
|
|
948
|
+
*
|
|
949
|
+
* **Optional** — the launch posture of every new family: not every
|
|
950
|
+
* example app authors assertions yet, and the family must not break
|
|
951
|
+
* existing companion exports on arrival. Once it graduates to
|
|
952
|
+
* required, app bootstraps should run
|
|
953
|
+
* `validateAssertionSpecificationSnapshot` on the value before
|
|
954
|
+
* wiring it here (the behavior resolver validates on entry either
|
|
955
|
+
* way, market-style).
|
|
956
|
+
*
|
|
957
|
+
* Lane discipline: entries carrying
|
|
958
|
+
* `lane: AssertionLane.FRAMEWORK_DEV` are framework-development
|
|
959
|
+
* knowledge (end-state platform bets authored in the dogfood app
|
|
960
|
+
* during the framework-parallel era) and must NEVER compile into
|
|
961
|
+
* shipped app knowledge — consumers filter on `lane` deliberately.
|
|
962
|
+
*/
|
|
963
|
+
assertionSpecifications?: TAssertionSpecifications;
|
|
964
|
+
// ── app-creation meta-workflows C-4 definition families (U1–U4) — FIELDS ──
|
|
965
|
+
// One field per family, in the SAME fixed order as the generic params
|
|
966
|
+
// above. All four are now registered (U1–U4 done); no reservation remains:
|
|
967
|
+
// 1. visionSpecification (U1 — below)
|
|
968
|
+
// 2. requirementsSpecification (U2 — below)
|
|
969
|
+
// 3. roadmapSpecification (U3 — below)
|
|
970
|
+
// 4. businessModelLiteSpecification (U4 — below, LAST)
|
|
971
|
+
/**
|
|
972
|
+
* Application **vision** specification — the foundational-intent truth
|
|
973
|
+
* (idea, problem statement, mission, success criteria, constraints incl.
|
|
974
|
+
* compliance) the app-creation top-down catalog reads/writes (C-4
|
|
975
|
+
* definition families). A single aggregate per app (market-snapshot
|
|
976
|
+
* style), validated by `validateVisionSnapshot`.
|
|
977
|
+
*
|
|
978
|
+
* **Optional** — the launch posture of every new family (market /
|
|
979
|
+
* assertions parity): not every example app authors a vision snapshot
|
|
980
|
+
* yet, and the family must not break existing companion exports on
|
|
981
|
+
* arrival. Once it graduates to required, app bootstraps should run
|
|
982
|
+
* `validateVisionSnapshot` on the value before wiring it here.
|
|
983
|
+
*/
|
|
984
|
+
visionSpecification?: TVisionSnapshot;
|
|
985
|
+
/**
|
|
986
|
+
* Application **requirements** specification — the requirements-layer
|
|
987
|
+
* truth (functional requirements + non-functional requirements, each
|
|
988
|
+
* optionally cross-referencing market ICPs / jobs) the app-creation
|
|
989
|
+
* top-down capability-map catalog reads/writes (C-4 definition
|
|
990
|
+
* families). A single aggregate per app (market-snapshot style),
|
|
991
|
+
* validated by `validateRequirementsSnapshot`.
|
|
992
|
+
*
|
|
993
|
+
* **Optional** — the launch posture of every new family (vision /
|
|
994
|
+
* market / assertions parity): not every example app authors a
|
|
995
|
+
* requirements snapshot yet, and the family must not break existing
|
|
996
|
+
* companion exports on arrival. Once it graduates to required, app
|
|
997
|
+
* bootstraps should run `validateRequirementsSnapshot` on the value
|
|
998
|
+
* before wiring it here.
|
|
999
|
+
*/
|
|
1000
|
+
requirementsSpecification?: TRequirementsSnapshot;
|
|
1001
|
+
/**
|
|
1002
|
+
* Application **roadmap** specification — the delivery-roadmap truth (a
|
|
1003
|
+
* product's delivery plan as an ordered collection of releases/phases,
|
|
1004
|
+
* each optionally cross-referencing the requirements /
|
|
1005
|
+
* vision-success-criteria it delivers) the app-creation top-down
|
|
1006
|
+
* scope/roadmap catalog reads/writes (C-4 definition families). A single
|
|
1007
|
+
* aggregate per app (market-snapshot style), validated by
|
|
1008
|
+
* `validateRoadmapSnapshot`. Distinct from `milestoneSpecifications` (a
|
|
1009
|
+
* dated registry-overlay surface) — a roadmap phase is a planning
|
|
1010
|
+
* artifact, not a runtime milestone.
|
|
1011
|
+
*
|
|
1012
|
+
* **Optional** — the launch posture of every new family (vision /
|
|
1013
|
+
* requirements / market / assertions parity): not every example app
|
|
1014
|
+
* authors a roadmap snapshot yet, and the family must not break existing
|
|
1015
|
+
* companion exports on arrival. Once it graduates to required, app
|
|
1016
|
+
* bootstraps should run `validateRoadmapSnapshot` on the value before
|
|
1017
|
+
* wiring it here.
|
|
1018
|
+
*/
|
|
1019
|
+
roadmapSpecification?: TRoadmapSnapshot;
|
|
1020
|
+
/**
|
|
1021
|
+
* Application **build-plan** specification — the ORDERED typed task graph
|
|
1022
|
+
* (`BuildPlanTaskGraph`, `_core/build-plan/`) that turns the accepted domain
|
|
1023
|
+
* plan into buildable units; produced by the build-decompose playbook and
|
|
1024
|
+
* consumed one READY task at a time by build-dispatch. Optional until an
|
|
1025
|
+
* application reaches the bottom-up phase; app bootstraps should run
|
|
1026
|
+
* `validateBuildPlanTaskGraph` on the value before wiring it here.
|
|
1027
|
+
*/
|
|
1028
|
+
buildPlanSpecification?: TBuildPlanTaskGraph;
|
|
1029
|
+
/**
|
|
1030
|
+
* Application **placement** specification — WHERE every settings destination,
|
|
1031
|
+
* resource operation and app view sits in the shell, and WHY (`PlacementPlan`,
|
|
1032
|
+
* `_core/placement-plan/`).
|
|
1033
|
+
*
|
|
1034
|
+
* Produced by the `bottom_up.placement-plan` playbook as an expert-panel
|
|
1035
|
+
* DELIBERATION rather than a creator elicitation: the creator does not choose
|
|
1036
|
+
* placement, so each decision carries a `rationale` that answers "why is this
|
|
1037
|
+
* here?" without re-running the panel. Consumed by build-decompose, which
|
|
1038
|
+
* turns it into the coding tasks that author `settings-hub.config.ts` and
|
|
1039
|
+
* `app-shell.config.ts`.
|
|
1040
|
+
*
|
|
1041
|
+
* Optional until an application reaches the bottom-up phase; app bootstraps
|
|
1042
|
+
* should run `validatePlacementPlan` on the value before wiring it here.
|
|
1043
|
+
*/
|
|
1044
|
+
placementPlanSpecification?: TPlacementPlan;
|
|
1045
|
+
/**
|
|
1046
|
+
* Application **domain-plan** specification — the atomic module decomposition
|
|
1047
|
+
* PLUS relationship drafts (`DomainPlanOutputSet`, `_core/domain-plan/`);
|
|
1048
|
+
* produced by the domain-plan playbook, decomposed by build-decompose.
|
|
1049
|
+
* Optional until an application reaches the bottom-up phase.
|
|
1050
|
+
*/
|
|
1051
|
+
domainPlanSpecification?: TDomainPlanOutputSet;
|
|
1052
|
+
/**
|
|
1053
|
+
* Application **business-model-lite** specification — the lightweight
|
|
1054
|
+
* business-model truth (a coarse product-level revenue model + a pricing-
|
|
1055
|
+
* plan sketch, each plan optionally cross-referencing the market ICPs it
|
|
1056
|
+
* targets and the requirements it includes) the app-creation top-down
|
|
1057
|
+
* catalog reads/writes (C-4 definition families). A single aggregate per
|
|
1058
|
+
* app (market-snapshot style), validated by
|
|
1059
|
+
* `validateBusinessModelLiteSnapshot`. A PLANNING artifact — deliberately
|
|
1060
|
+
* NOT the live billing / Stripe product-catalog runtime (it models
|
|
1061
|
+
* pricing INTENT, never chargeable state). The `-lite` is the
|
|
1062
|
+
* scaffold-depth qualifier of the Phase-J1 increment; the artifact-family
|
|
1063
|
+
* id is `business-model`.
|
|
1064
|
+
*
|
|
1065
|
+
* **Optional** — the launch posture of every new family (vision /
|
|
1066
|
+
* requirements / roadmap / market / assertions parity): not every example
|
|
1067
|
+
* app authors a business-model snapshot yet, and the family must not break
|
|
1068
|
+
* existing companion exports on arrival. Once it graduates to required,
|
|
1069
|
+
* app bootstraps should run `validateBusinessModelLiteSnapshot` on the
|
|
1070
|
+
* value before wiring it here.
|
|
1071
|
+
*/
|
|
1072
|
+
businessModelLiteSpecification?: TBusinessModelLiteSnapshot;
|
|
1073
|
+
/**
|
|
1074
|
+
* Application **brand** specification — the visual-identity brief (brand
|
|
1075
|
+
* name + logo direction + visual tone; `resolvedAssets` populated by the
|
|
1076
|
+
* companion logo step) the app-creation top-down `brand-identity` playbook
|
|
1077
|
+
* reads/writes. A single aggregate per app (vision-snapshot style),
|
|
1078
|
+
* validated by `validateBrandSnapshot`. Read by the companion
|
|
1079
|
+
* `brand-render-prompt` behavior to assemble the logo generation prompt;
|
|
1080
|
+
* the artifact-family id is `brand-brief`.
|
|
1081
|
+
*
|
|
1082
|
+
* **Optional** — the launch posture of every new family: not every example
|
|
1083
|
+
* app authors a brand snapshot yet, and the family must not break existing
|
|
1084
|
+
* companion exports on arrival.
|
|
1085
|
+
*/
|
|
1086
|
+
brandSpecification?: TBrandSnapshot;
|
|
1087
|
+
/**
|
|
1088
|
+
* Application **expert-persona charters** — the DERIVED worker-persona
|
|
1089
|
+
* instances (`ExpertPersonaCharter[]`) of the framework's
|
|
1090
|
+
* `EXPERT_ROLE_TEMPLATES` (art-director, copy-chief, …), committed under
|
|
1091
|
+
* `specifications/src/personas/` by the companion's derive→accept flow
|
|
1092
|
+
* (and hand-editable thereafter; a human edit is recorded in `authored`).
|
|
1093
|
+
*
|
|
1094
|
+
* Consumed by the companion's `expert-persona-charters` introspection
|
|
1095
|
+
* behavior: the deliberation system builds each expert's agent from the
|
|
1096
|
+
* committed charter at startup, and the accept step reads the set for its
|
|
1097
|
+
* human-edit overwrite guard + `validateExpertPersonaCharters` run.
|
|
1098
|
+
*
|
|
1099
|
+
* PLURAL by design (unlike the singleton snapshot families above): an app
|
|
1100
|
+
* has one charter per role, several roles. Distinct from the market
|
|
1101
|
+
* family's `personas` (BUYER personas — who the app sells to); these are
|
|
1102
|
+
* WORKER personas (who does the creative work).
|
|
1103
|
+
*
|
|
1104
|
+
* **Optional** — the launch posture of every new family: not every example
|
|
1105
|
+
* app has derived charters yet, and the family must not break existing
|
|
1106
|
+
* companion exports on arrival. Apps with charters should export the
|
|
1107
|
+
* generated `appExpertPersonaCharters` aggregate from
|
|
1108
|
+
* `specifications/src/personas/`.
|
|
1109
|
+
*/
|
|
1110
|
+
expertPersonaCharters?: TExpertPersonaCharters;
|
|
1111
|
+
/**
|
|
1112
|
+
* Accepted **feature drafts** produced by the top-down capability-map.
|
|
1113
|
+
*
|
|
1114
|
+
* Drafts carry product intent only: purpose, business role, lifecycle and
|
|
1115
|
+
* availability guidance. They deliberately exclude runtime-definition
|
|
1116
|
+
* provenance and executable scope. Phase-gate and domain-planning evidence
|
|
1117
|
+
* consume this member; `featureSpecifications` remains the separate
|
|
1118
|
+
* runtime-backed overlay surface used after capabilities are implemented.
|
|
1119
|
+
*
|
|
1120
|
+
* **Optional** at the aggregate contract boundary because applications that
|
|
1121
|
+
* have not entered the app-creation workflow may not have accepted drafts.
|
|
1122
|
+
* A treatment selecting the `feature-drafts` family fails closed when the
|
|
1123
|
+
* member is absent.
|
|
1124
|
+
*/
|
|
1125
|
+
featureDraftsSpecification?: TFeatureSpecificationDrafts;
|
|
1126
|
+
/**
|
|
1127
|
+
* Accepted application **compliance program** policy.
|
|
1128
|
+
*
|
|
1129
|
+
* This is the configured application's reusable source/scope/objective,
|
|
1130
|
+
* implementation-choice, responsibility, gap/exception and documentation
|
|
1131
|
+
* truth. It deliberately excludes live organizations, assignees, reviewer
|
|
1132
|
+
* identities, evidence bytes and operating-effectiveness claims.
|
|
1133
|
+
*
|
|
1134
|
+
* **Optional** at launch. If the application declares the
|
|
1135
|
+
* `compliance-program` family, the semantic family authority requires this
|
|
1136
|
+
* member and validates it fail closed. Applications without that family must
|
|
1137
|
+
* not synthesize this value or receive positive compliance-program claims.
|
|
1138
|
+
*/
|
|
1139
|
+
complianceSpecification?: TComplianceSpecification;
|
|
1140
|
+
/**
|
|
1141
|
+
* Accepted application **public-document publication variants**.
|
|
1142
|
+
*
|
|
1143
|
+
* The exact locale × jurisdiction combinations in which this application
|
|
1144
|
+
* publishes public governed documents. It is the ONLY source a governed
|
|
1145
|
+
* document candidate may take its locale and jurisdictions from: the
|
|
1146
|
+
* candidate host seals these bytes into a publication-variant authority
|
|
1147
|
+
* bound to the `document-publication` family's retained head, and refuses
|
|
1148
|
+
* any combination that is not an exact member.
|
|
1149
|
+
*
|
|
1150
|
+
* Distinct from `complianceSpecification` by design. The assurance program
|
|
1151
|
+
* decides which documents are required and who approves them; this slot
|
|
1152
|
+
* decides where and in which language they are published. Folding the two
|
|
1153
|
+
* would let a document requirement widen its own publication routing.
|
|
1154
|
+
*
|
|
1155
|
+
* **Optional** at the aggregate contract boundary. An application that
|
|
1156
|
+
* declares no `document-publication` family publishes no public governed
|
|
1157
|
+
* document, and candidate creation fails closed rather than defaulting to a
|
|
1158
|
+
* locale or jurisdiction nobody accepted.
|
|
1159
|
+
*/
|
|
1160
|
+
documentPublicationSpecification?: TDocumentPublicationSpecification;
|
|
1161
|
+
/**
|
|
1162
|
+
* Accepted application selection of the human release lane for each exact
|
|
1163
|
+
* governed-document requirement. Optional at the aggregate boundary: an
|
|
1164
|
+
* application with no policy can still generate a working draft, but every
|
|
1165
|
+
* exposure attempt fails closed rather than assuming operator attestation or
|
|
1166
|
+
* qualified review.
|
|
1167
|
+
*/
|
|
1168
|
+
documentReleasePolicySpecification?: TDocumentReleasePolicySpecification;
|
|
1169
|
+
/**
|
|
1170
|
+
* Accepted application **governed-document facts**.
|
|
1171
|
+
*
|
|
1172
|
+
* This optional slot carries raw application, creator-decision and
|
|
1173
|
+
* qualified-review fact declarations from the dedicated `document-facts`
|
|
1174
|
+
* specification family. The application-creation host validates the exact
|
|
1175
|
+
* accepted family head and seals derived contribution digests and validation
|
|
1176
|
+
* receipts; application code never authors those host identities.
|
|
1177
|
+
*
|
|
1178
|
+
* Reviewer authority grants, review decisions, candidates and immutable
|
|
1179
|
+
* releases are runtime/private custody and are forbidden from this slot.
|
|
1180
|
+
* Omitting it is honest: unresolved document facts remain visible gaps.
|
|
1181
|
+
*/
|
|
1182
|
+
documentFactSpecification?: TDocumentFactSpecification;
|
|
1183
|
+
/**
|
|
1184
|
+
* WHO else processes this application's personal data — legal identity, processing region and the
|
|
1185
|
+
* processor's own subprocessors (issue #88).
|
|
1186
|
+
*
|
|
1187
|
+
* A configured provider already establishes THAT a third party is involved and what function it
|
|
1188
|
+
* performs. None of that is what a privacy notice's recipient statement needs, and an
|
|
1189
|
+
* international-transfer statement cannot be made at all without a region.
|
|
1190
|
+
*
|
|
1191
|
+
* Optional, and its holes are reported rather than blocking: the companion compares this register
|
|
1192
|
+
* against the application's CONFIGURED providers and names each one that is undeclared, so a partial
|
|
1193
|
+
* register is useful and an empty one still produces an actionable document. An absent entry means
|
|
1194
|
+
* nobody has established that processor's identity — never that the provider is unused.
|
|
1195
|
+
*/
|
|
1196
|
+
processorRegister?: TProcessorRegister;
|
|
1197
|
+
/**
|
|
1198
|
+
* Accepted application-declared semantic causality between whole
|
|
1199
|
+
* specification-family states. This is not the registry's physical
|
|
1200
|
+
* dependency graph and not Actor/Flow execution order. The runtime resolves
|
|
1201
|
+
* these declarations only through the exact CURRENT accepted projection,
|
|
1202
|
+
* then may derive a rebuildable impact index; this export itself does not
|
|
1203
|
+
* authorize a journal write, review queue or application mutation.
|
|
1204
|
+
*
|
|
1205
|
+
* Optional because semantic impact is an advanced application-creation
|
|
1206
|
+
* capability. An application that declares the dedicated
|
|
1207
|
+
* `semantic-dependencies` family must provide this field; a resolver refuses
|
|
1208
|
+
* a missing or malformed value rather than infer dependencies from imports
|
|
1209
|
+
* or registry edges.
|
|
1210
|
+
*/
|
|
1211
|
+
}
|
|
1212
|
+
|
|
1213
|
+
/**
|
|
1214
|
+
* Aggregate of every catalog vocabulary an app can wire on the
|
|
1215
|
+
* `catalogSpecifications` companion-exports slot.
|
|
1216
|
+
*
|
|
1217
|
+
* Each vocabulary is a flat array of validated entries (engine
|
|
1218
|
+
* + app entries merged at wiring time). The companion harness keys
|
|
1219
|
+
* each vocabulary by its discriminator (`@type` for Schema.org;
|
|
1220
|
+
* future vocabularies can use `operationId`, `kind`, etc.); app
|
|
1221
|
+
* entries silently override engine entries on collision and the
|
|
1222
|
+
* harness emits a `catalog-override` warning for each override at
|
|
1223
|
+
* boot.
|
|
1224
|
+
*
|
|
1225
|
+
* **Why an aggregate type and not per-slot fields**: every future
|
|
1226
|
+
* vocabulary lands as a sibling field on this single type rather
|
|
1227
|
+
* than as a new top-level companion-exports field. This keeps the
|
|
1228
|
+
* `SpecificationsCompanionExports` shape stable as the catalog
|
|
1229
|
+
* surface grows.
|
|
1230
|
+
*/
|
|
1231
|
+
export interface CatalogSpecifications {
|
|
1232
|
+
/**
|
|
1233
|
+
* Schema.org JSON-LD vocabulary catalog. Compose with
|
|
1234
|
+
* `ENGINE_SCHEMA_ORG_CATALOG` (engine-shipped standard entries)
|
|
1235
|
+
* spread, then append app-side extensions / overrides.
|
|
1236
|
+
*/
|
|
1237
|
+
schemaOrg?: readonly SchemaOrgCatalogEntryBase[];
|
|
1238
|
+
}
|
|
1239
|
+
```
|
|
1240
|
+
|
|
1241
|
+
## Validator coupling (source)
|
|
1242
|
+
|
|
1243
|
+
Templates paired with the rendered block are policed by
|
|
1244
|
+
`MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` (validator §10.3 / 18th
|
|
1245
|
+
issue kind). The full validator JSDoc + rule table lives under the
|
|
1246
|
+
existing `market.snapshot.validation` anchor:
|
|
1247
|
+
|
|
1248
|
+
## Import Origins
|
|
1249
|
+
|
|
1250
|
+
- `@wildo-ai/saas-specifications`
|
|
1251
|
+
|
|
1252
|
+
## Source Excerpts
|
|
1253
|
+
|
|
1254
|
+
### Origin Package: `@wildo-ai/saas-specifications`
|
|
1255
|
+
|
|
1256
|
+
```typescript
|
|
1257
|
+
*
|
|
1258
|
+
* Authoring-consistency validator for an assembled `MarketSnapshot`.
|
|
1259
|
+
*
|
|
1260
|
+
* The function is a **pure**, **typed** graph walker over the
|
|
1261
|
+
* snapshot — no Zod introspection, no LocalizedString visitor, no
|
|
1262
|
+
* runtime registry access. Each rule is implemented as a tiny
|
|
1263
|
+
* standalone detector composed by the top-level
|
|
1264
|
+
* `validateMarketSnapshot`.
|
|
1265
|
+
*
|
|
1266
|
+
* Rule table — currently 18 kinds:
|
|
1267
|
+
*
|
|
1268
|
+
* | Kind | Severity | Trigger |
|
|
1269
|
+
* |--------------------------------------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
|
|
1270
|
+
* | `ORPHAN_REF` | ERROR | A `<entity>Ref` does not resolve inside the snapshot. Cross-family refs (`featureRefs`, `productRefs`) are skipped if no set is passed. |
|
|
1271
|
+
* | `MULTIPLE_THRESHOLDS_PER_ICP_JOB` | ERROR | An (icpRef, jobRef) cluster has more than one distinct benefit with `kanoCategory: THRESHOLD`. Deduped by benefit `ref`. |
|
|
1272
|
+
* | `THRESHOLD_BENEFIT_WITHOUT_JOB` | ERROR | A benefit declares any `kanoCategory: THRESHOLD` entry but `advances[]` is empty (no job to anchor the THRESHOLD claim against). |
|
|
1273
|
+
* | `EMPTY_BENEFIT_DELIVERED_BY` | ERROR | A `FeatureBenefit.deliveredByFeatureRefs[]` is empty (defence in depth — Zod also rejects). |
|
|
1274
|
+
* | `ICP_WITHOUT_PERSONA` | ERROR (LEGAL_ENTITY) / WARN (INDIVIDUAL) | A non-`ANTI_TARGET` ICP has no persona pointing at its `ref` via `belongsToIcpRefs`. |
|
|
1275
|
+
* | `INFLUENCE_CYCLE` | ERROR (self-loop) / WARN (multi-node) | Cycle in the ICP→ICP influence graph. Self-loops are always ERROR; non-trivial cycles are WARN (real GTM dynamics may include them). |
|
|
1276
|
+
* | `MISSING_POSITIONING_FOR_ICP` | ERROR | An ICP of priority `CORE` or `EXPANSION` has no `MarketPositioning`. Other priorities exempt. |
|
|
1277
|
+
* | `STALE_AUTHORED` | WARN | `lastAuthoredAt + reviewCadence < now`. No check when `reviewCadence` is undefined or `AS_NEEDED`. |
|
|
1278
|
+
* | `DUPLICATE_EDGE_PER_ENTITY` | WARN | Same target ref appears twice in the same edge list. Covers ICP/persona `pains/gains/jobs` (by edge ref) and benefit `importanceByICP` (by `icpRef`). |
|
|
1279
|
+
* | `INVALID_ANTI_TARGET_PURPOSE_MIX` | ERROR | `priority === ANTI_TARGET` and `purposeMix !== { adoption: 0, revenue: 0 }`. |
|
|
1280
|
+
* | `BUYING_GROUP_PERSONA_MISSING_DMU_ROLE` | ERROR | `personaScope === BUYING_GROUP_MEMBER` and `dmuRole` is undefined. |
|
|
1281
|
+
* | `BUYING_GROUP_BACKLINK_MISSING` | ERROR | An ICP's `buyingGroup[].personaRef` resolves to a persona whose `belongsToIcpRefs[]` does NOT include the ICP (asymmetric link). |
|
|
1282
|
+
* | `PROOF_WITHOUT_SUPPORT` | WARN | A `MarketProof` carries empty `supportsBenefitRefs[]` AND empty `supportsIcpRefs[]`. |
|
|
1283
|
+
* | `PROOF_KIND_PAYLOAD_MISMATCH` | WARN | A `MarketProof` carries a payload incoherent with its `proofKind` (`METRIC` without `metric`, `LOGO` with `metric`). |
|
|
1284
|
+
* | `DUPLICATE_JOURNEY_STAGE` | ERROR | A `MarketBuyingJourney` lists the same `BuyingJourneyStage` enum value more than once. |
|
|
1285
|
+
* | `DUPLICATE_BUYING_JOURNEY_FOR_ICP` | ERROR | Two `MarketBuyingJourney` entries point at the same `icpRef`. The model is "one journey per ICP". |
|
|
1286
|
+
* | `OBJECTION_PROOF_BENEFIT_MISMATCH` | WARN | An objection cites `proofRefs[]` whose union of `supportsBenefitRefs[]` ∪ `supportsIcpRefs[]` does not intersect `relatedBenefitRefs[]` ∪ `raisedByIcpRefs[]`. |
|
|
1287
|
+
* | `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` | WARN | A `MarketMessageTemplate` declares a `requiredInputs[]` entry that no `{{<entity>.*}}` / `{{<entity>Ref}}` placeholder consumes — or vice-versa. `{{output_language}}` is exempt (CLI-injected at render time). |
|
|
1288
|
+
*
|
|
1289
|
+
* Issue ordering inside `result.issues[]` is detector-order, then
|
|
1290
|
+
* snapshot-walk order. It is **not** a stable contract — callers
|
|
1291
|
+
* must group/sort by `kind` + `severity` themselves.
|
|
1292
|
+
*
|
|
1293
|
+
* Loaded by application registries at boot. Callers should:
|
|
1294
|
+
* - throw a `BusinessConfigError` (re-exported from
|
|
1295
|
+
* `@wildo-ai/saas-backend-lib`) when `result.ok === false`,
|
|
1296
|
+
* listing every ERROR-severity issue;
|
|
1297
|
+
* - log WARN-severity issues through the standard backend logger.
|
|
1298
|
+
*
|
|
1299
|
+
* The validator never mutates the snapshot.
|
|
1300
|
+
*/
|
|
1301
|
+
export enum MarketSnapshotIssueKind {
|
|
1302
|
+
ORPHAN_REF = 'ORPHAN_REF',
|
|
1303
|
+
MULTIPLE_THRESHOLDS_PER_ICP_JOB = 'MULTIPLE_THRESHOLDS_PER_ICP_JOB',
|
|
1304
|
+
/**
|
|
1305
|
+
* A benefit declares any `kanoCategory: THRESHOLD` entry on
|
|
1306
|
+
* `importanceByICP[]` but its `advances[]` is empty. THRESHOLD is
|
|
1307
|
+
* defined as "table-stakes for a specific (icp, job)" — without a
|
|
1308
|
+
* job to anchor against, the THRESHOLD claim has no semantic
|
|
1309
|
+
* cluster and the `MULTIPLE_THRESHOLDS_PER_ICP_JOB` invariant is
|
|
1310
|
+
* structurally bypassed (ERROR).
|
|
1311
|
+
*/
|
|
1312
|
+
THRESHOLD_BENEFIT_WITHOUT_JOB = 'THRESHOLD_BENEFIT_WITHOUT_JOB',
|
|
1313
|
+
EMPTY_BENEFIT_DELIVERED_BY = 'EMPTY_BENEFIT_DELIVERED_BY',
|
|
1314
|
+
ICP_WITHOUT_PERSONA = 'ICP_WITHOUT_PERSONA',
|
|
1315
|
+
INFLUENCE_CYCLE = 'INFLUENCE_CYCLE',
|
|
1316
|
+
MISSING_POSITIONING_FOR_ICP = 'MISSING_POSITIONING_FOR_ICP',
|
|
1317
|
+
STALE_AUTHORED = 'STALE_AUTHORED',
|
|
1318
|
+
/**
|
|
1319
|
+
* Same target ref appears more than once in the same per-entity
|
|
1320
|
+
* edge list. Currently covers:
|
|
1321
|
+
* - ICP and persona `pains[].painRef`, `gains[].gainRef`,
|
|
1322
|
+
* `jobs[].jobRef` — typically the result of an `inheritFrom()`
|
|
1323
|
+
* spread followed by a forgotten `.filter()` step;
|
|
1324
|
+
* - benefit `importanceByICP[].icpRef` — duplicate (benefit, icp)
|
|
1325
|
+
* pairs make per-ICP scoring non-deterministic.
|
|
1326
|
+
*
|
|
1327
|
+
* Severity is WARN — the snapshot still parses, but the duplicate
|
|
1328
|
+
* edge silently double-counts in downstream FIT scoring.
|
|
1329
|
+
*/
|
|
1330
|
+
DUPLICATE_EDGE_PER_ENTITY = 'DUPLICATE_EDGE_PER_ENTITY',
|
|
1331
|
+
INVALID_ANTI_TARGET_PURPOSE_MIX = 'INVALID_ANTI_TARGET_PURPOSE_MIX',
|
|
1332
|
+
BUYING_GROUP_PERSONA_MISSING_DMU_ROLE = 'BUYING_GROUP_PERSONA_MISSING_DMU_ROLE',
|
|
1333
|
+
/**
|
|
1334
|
+
* An ICP's `buyingGroup[].personaRef` resolves to a persona, but
|
|
1335
|
+
* the persona's `belongsToIcpRefs[]` does not contain the ICP. The
|
|
1336
|
+
* link is asymmetric and downstream consumers (DMU rendering,
|
|
1337
|
+
* persona-by-ICP indexing) silently drop the persona. ERROR.
|
|
1338
|
+
*/
|
|
1339
|
+
BUYING_GROUP_BACKLINK_MISSING = 'BUYING_GROUP_BACKLINK_MISSING',
|
|
1340
|
+
/** A proof entity that supports neither a benefit nor an ICP — has no place to land in copy (WARN). */
|
|
1341
|
+
PROOF_WITHOUT_SUPPORT = 'PROOF_WITHOUT_SUPPORT',
|
|
1342
|
+
/**
|
|
1343
|
+
* A `MarketProof` carries a payload incoherent with its
|
|
1344
|
+
* `proofKind`. The schema is permissive (both `attribution` and
|
|
1345
|
+
* `metric` are optional on every kind). This detector catches the
|
|
1346
|
+
* strongest mismatches as authoring drift (WARN — the spec parses,
|
|
1347
|
+
* but the proof renders badly):
|
|
1348
|
+
* - `METRIC` without a `metric` block;
|
|
1349
|
+
* - `LOGO` with a `metric` block.
|
|
1350
|
+
*/
|
|
1351
|
+
PROOF_KIND_PAYLOAD_MISMATCH = 'PROOF_KIND_PAYLOAD_MISMATCH',
|
|
1352
|
+
/** Same `BuyingJourneyStage` enum value listed twice on a single journey (ERROR). */
|
|
1353
|
+
DUPLICATE_JOURNEY_STAGE = 'DUPLICATE_JOURNEY_STAGE',
|
|
1354
|
+
/** Two `MarketBuyingJourney` entries point at the same `icpRef`. The model is one journey per ICP (ERROR). */
|
|
1355
|
+
DUPLICATE_BUYING_JOURNEY_FOR_ICP = 'DUPLICATE_BUYING_JOURNEY_FOR_ICP',
|
|
1356
|
+
/** Objection's cited proofs do not back any of its `relatedBenefitRefs` or `raisedByIcpRefs` (WARN). */
|
|
1357
|
+
OBJECTION_PROOF_BENEFIT_MISMATCH = 'OBJECTION_PROOF_BENEFIT_MISMATCH',
|
|
1358
|
+
/**
|
|
1359
|
+
* A `MarketMessageTemplate` has a mismatch between its declared
|
|
1360
|
+
* `requiredInputs[]` and the `{{<entity>.*}}` / `{{<entity>Ref}}`
|
|
1361
|
+
* placeholders that actually appear inside `promptTemplate`.
|
|
1362
|
+
*
|
|
1363
|
+
* Two symmetric cases:
|
|
1364
|
+
* 1. Declared but unused — `requiredInputs` lists `icpRef` but the
|
|
1365
|
+
* body has no `{{icp.*}}` / `{{icpRef}}` reference. The CLI will
|
|
1366
|
+
* require the caller to pass the input but never substitute it.
|
|
1367
|
+
* 2. Used but undeclared — the body references `{{benefit.claim}}`
|
|
1368
|
+
* but `requiredInputs` does not include `benefitRef`. The CLI
|
|
1369
|
+
* will not enforce the input and the placeholder will render
|
|
1370
|
+
* literally (e.g. `{{benefit.claim}}`).
|
|
1371
|
+
*
|
|
1372
|
+
* The `{{output_language}}` placeholder is **exempt** from this
|
|
1373
|
+
* check: it is injected by the market generation CLI from the
|
|
1374
|
+
* `--output-language` flag, not from `requiredInputs[]`.
|
|
1375
|
+
*
|
|
1376
|
+
* WARN severity — the snapshot still parses and the template still
|
|
1377
|
+
* renders, but the output will be off-spec at runtime. Authors
|
|
1378
|
+
* should either prune the unused entry from `requiredInputs[]` or
|
|
1379
|
+
* add the missing placeholder / entry.
|
|
1380
|
+
*/
|
|
1381
|
+
MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH = 'MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH',
|
|
1382
|
+
}
|
|
1383
|
+
|
|
1384
|
+
export type MarketSnapshotIssueSeverity = 'ERROR' | 'WARN';
|
|
1385
|
+
|
|
1386
|
+
export interface MarketSnapshotIssue {
|
|
1387
|
+
kind: MarketSnapshotIssueKind;
|
|
1388
|
+
/** Dotted path inside the snapshot (e.g. `'icps[0].pains[2].painRef'`). */
|
|
1389
|
+
path: string;
|
|
1390
|
+
message: string;
|
|
1391
|
+
severity: MarketSnapshotIssueSeverity;
|
|
1392
|
+
}
|
|
1393
|
+
|
|
1394
|
+
export interface MarketSnapshotValidationResult {
|
|
1395
|
+
/** `true` iff no issue has severity `ERROR`. */
|
|
1396
|
+
ok: boolean;
|
|
1397
|
+
issues: MarketSnapshotIssue[];
|
|
1398
|
+
}
|
|
1399
|
+
|
|
1400
|
+
export interface ValidateMarketSnapshotOptions {
|
|
1401
|
+
/**
|
|
1402
|
+
* Cross-family ref check for `FeatureBenefit.deliveredByFeatureRefs`.
|
|
1403
|
+
* Pass the application's full feature-spec key set; orphans are
|
|
1404
|
+
* reported as `ORPHAN_REF`. When omitted, the cross-family check is
|
|
1405
|
+
* SKIPPED (intra-snapshot orphans are still detected).
|
|
1406
|
+
*/
|
|
1407
|
+
availableFeatureRefs?: ReadonlySet<string>;
|
|
1408
|
+
/**
|
|
1409
|
+
* Cross-family ref check for `MarketICP.recommendedProductRefs` /
|
|
1410
|
+
* `upsellPathProductRefs`. Same skip-when-omitted semantics.
|
|
1411
|
+
*/
|
|
1412
|
+
availableProductRefs?: ReadonlySet<string>;
|
|
1413
|
+
/** Override "now" for `STALE_AUTHORED` checks (test affordance). Defaults to `new Date()`. */
|
|
1414
|
+
now?: Date;
|
|
1415
|
+
}
|
|
1416
|
+
|
|
1417
|
+
export function validateMarketSnapshot(
|
|
1418
|
+
snapshot: MarketSnapshot,
|
|
1419
|
+
options?: ValidateMarketSnapshotOptions,
|
|
1420
|
+
): MarketSnapshotValidationResult {
|
|
1421
|
+
const issues: MarketSnapshotIssue[] = [];
|
|
1422
|
+
|
|
1423
|
+
detectOrphanRefs(snapshot, options, issues);
|
|
1424
|
+
detectThresholdBenefitsWithoutJob(snapshot, issues);
|
|
1425
|
+
detectMultipleThresholdsPerIcpJob(snapshot, issues);
|
|
1426
|
+
detectEmptyBenefitDeliveredBy(snapshot, issues);
|
|
1427
|
+
detectIcpWithoutPersona(snapshot, issues);
|
|
1428
|
+
detectInfluenceCycles(snapshot, issues);
|
|
1429
|
+
detectMissingPositioningForIcp(snapshot, issues);
|
|
1430
|
+
detectStaleAuthored(snapshot, options?.now ?? new Date(), issues);
|
|
1431
|
+
detectDuplicateEdgesPerEntity(snapshot, issues);
|
|
1432
|
+
detectInvalidAntiTargetPurposeMix(snapshot, issues);
|
|
1433
|
+
detectBuyingGroupPersonasMissingDmuRole(snapshot, issues);
|
|
1434
|
+
detectBuyingGroupBacklinkMissing(snapshot, issues);
|
|
1435
|
+
detectProofsWithoutSupport(snapshot, issues);
|
|
1436
|
+
detectProofKindPayloadMismatch(snapshot, issues);
|
|
1437
|
+
detectDuplicateJourneyStages(snapshot, issues);
|
|
1438
|
+
detectDuplicateBuyingJourneyForIcp(snapshot, issues);
|
|
1439
|
+
detectObjectionProofBenefitMismatch(snapshot, issues);
|
|
1440
|
+
detectMessageTemplatePlaceholderMismatch(snapshot, issues);
|
|
1441
|
+
|
|
1442
|
+
const ok = issues.every(i => i.severity !== 'ERROR');
|
|
1443
|
+
return { ok, issues };
|
|
1444
|
+
}
|
|
1445
|
+
|
|
1446
|
+
// ────────────────────────────────────────────────────────────────────
|
|
1447
|
+
// Detectors — one per rule, kept small and independently testable.
|
|
1448
|
+
// ────────────────────────────────────────────────────────────────────
|
|
1449
|
+
|
|
1450
|
+
function detectOrphanRefs(
|
|
1451
|
+
snapshot: MarketSnapshot,
|
|
1452
|
+
options: ValidateMarketSnapshotOptions | undefined,
|
|
1453
|
+
issues: MarketSnapshotIssue[],
|
|
1454
|
+
): void {
|
|
1455
|
+
const icpRefs = new Set(snapshot.icps.map(i => i.ref));
|
|
1456
|
+
const personaRefs = new Set(snapshot.personas.map(p => p.ref));
|
|
1457
|
+
const jobRefs = new Set(snapshot.jobs.map(j => j.ref));
|
|
1458
|
+
const painRefs = new Set(snapshot.pains.map(p => p.ref));
|
|
1459
|
+
const gainRefs = new Set(snapshot.gains.map(g => g.ref));
|
|
1460
|
+
const voiceRefs = new Set(snapshot.tonesOfVoice.map(v => v.ref));
|
|
1461
|
+
const benefitRefs = new Set(snapshot.benefits.map(b => b.ref));
|
|
1462
|
+
const channelRefs = new Set(snapshot.channels.map(c => c.ref));
|
|
1463
|
+
const alternativeRefs = new Set(snapshot.alternatives.map(a => a.ref));
|
|
1464
|
+
const triggerRefs = new Set(snapshot.triggers.map(t => t.ref));
|
|
1465
|
+
const proofRefs = new Set(snapshot.proofs.map(p => p.ref));
|
|
1466
|
+
const objectionRefs = new Set(snapshot.objections.map(o => o.ref));
|
|
1467
|
+
|
|
1468
|
+
const reportOrphan = (path: string, ref: string, kind: string): void => {
|
|
1469
|
+
issues.push({
|
|
1470
|
+
kind: MarketSnapshotIssueKind.ORPHAN_REF,
|
|
1471
|
+
path,
|
|
1472
|
+
message: `${kind} ref "${ref}" at ${path} does not resolve inside the snapshot.`,
|
|
1473
|
+
severity: 'ERROR',
|
|
1474
|
+
});
|
|
1475
|
+
};
|
|
1476
|
+
|
|
1477
|
+
// ICP edges + cross-family + influences + voices + Phase-3 ref arrays.
|
|
1478
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
1479
|
+
const basePath = `icps[${iIdx}]`;
|
|
1480
|
+
|
|
1481
|
+
icp.buyingGroup.forEach((entry, idx) => {
|
|
1482
|
+
if (!personaRefs.has(entry.personaRef)) {
|
|
1483
|
+
reportOrphan(`${basePath}.buyingGroup[${idx}].personaRef`, entry.personaRef, 'persona');
|
|
1484
|
+
}
|
|
1485
|
+
});
|
|
1486
|
+
icp.jobs.forEach((edge, idx) => {
|
|
1487
|
+
if (!jobRefs.has(edge.jobRef)) reportOrphan(`${basePath}.jobs[${idx}].jobRef`, edge.jobRef, 'job');
|
|
1488
|
+
});
|
|
1489
|
+
icp.pains.forEach((edge, idx) => {
|
|
1490
|
+
if (!painRefs.has(edge.painRef)) reportOrphan(`${basePath}.pains[${idx}].painRef`, edge.painRef, 'pain');
|
|
1491
|
+
});
|
|
1492
|
+
icp.gains.forEach((edge, idx) => {
|
|
1493
|
+
if (!gainRefs.has(edge.gainRef)) reportOrphan(`${basePath}.gains[${idx}].gainRef`, edge.gainRef, 'gain');
|
|
1494
|
+
});
|
|
1495
|
+
icp.influences.forEach((edge, idx) => {
|
|
1496
|
+
if (!icpRefs.has(edge.icpRef)) reportOrphan(`${basePath}.influences[${idx}].icpRef`, edge.icpRef, 'icp');
|
|
1497
|
+
});
|
|
1498
|
+
if (icp.preferredVoiceRef !== undefined && !voiceRefs.has(icp.preferredVoiceRef)) {
|
|
1499
|
+
reportOrphan(`${basePath}.preferredVoiceRef`, icp.preferredVoiceRef, 'voice');
|
|
1500
|
+
}
|
|
1501
|
+
|
|
1502
|
+
// Phase-3 ICP ref arrays (channels / triggers / alternatives /
|
|
1503
|
+
// proofs / objections). All are intra-snapshot — no caller-supplied
|
|
1504
|
+
// set required. Orphans here silently waste downstream targeting
|
|
1505
|
+
// (channel never reached, trigger never observed) so ERROR is the
|
|
1506
|
+
// right severity (D16).
|
|
1507
|
+
icp.channelRefs.forEach((ref, idx) => {
|
|
1508
|
+
if (!channelRefs.has(ref)) reportOrphan(`${basePath}.channelRefs[${idx}]`, ref, 'channel');
|
|
1509
|
+
});
|
|
1510
|
+
icp.triggerRefs.forEach((ref, idx) => {
|
|
1511
|
+
if (!triggerRefs.has(ref)) reportOrphan(`${basePath}.triggerRefs[${idx}]`, ref, 'trigger');
|
|
1512
|
+
});
|
|
1513
|
+
icp.alternativeRefs.forEach((ref, idx) => {
|
|
1514
|
+
if (!alternativeRefs.has(ref)) reportOrphan(`${basePath}.alternativeRefs[${idx}]`, ref, 'alternative');
|
|
1515
|
+
});
|
|
1516
|
+
icp.proofRefs.forEach((ref, idx) => {
|
|
1517
|
+
if (!proofRefs.has(ref)) reportOrphan(`${basePath}.proofRefs[${idx}]`, ref, 'proof');
|
|
1518
|
+
});
|
|
1519
|
+
icp.objectionRefs.forEach((ref, idx) => {
|
|
1520
|
+
if (!objectionRefs.has(ref)) reportOrphan(`${basePath}.objectionRefs[${idx}]`, ref, 'objection');
|
|
1521
|
+
});
|
|
1522
|
+
|
|
1523
|
+
if (options?.availableProductRefs !== undefined) {
|
|
1524
|
+
icp.recommendedProductRefs.forEach((ref, idx) => {
|
|
1525
|
+
if (!options.availableProductRefs!.has(ref)) {
|
|
1526
|
+
reportOrphan(`${basePath}.recommendedProductRefs[${idx}]`, ref, 'product');
|
|
1527
|
+
}
|
|
1528
|
+
});
|
|
1529
|
+
icp.upsellPathProductRefs.forEach((ref, idx) => {
|
|
1530
|
+
if (!options.availableProductRefs!.has(ref)) {
|
|
1531
|
+
reportOrphan(`${basePath}.upsellPathProductRefs[${idx}]`, ref, 'product');
|
|
1532
|
+
}
|
|
1533
|
+
});
|
|
1534
|
+
}
|
|
1535
|
+
}
|
|
1536
|
+
|
|
1537
|
+
// Persona edges + cross-family voice ref + parent ICP refs + Phase-3
|
|
1538
|
+
// channel refs.
|
|
1539
|
+
for (const [pIdx, persona] of snapshot.personas.entries()) {
|
|
1540
|
+
const basePath = `personas[${pIdx}]`;
|
|
1541
|
+
|
|
1542
|
+
persona.belongsToIcpRefs.forEach((ref, idx) => {
|
|
1543
|
+
if (!icpRefs.has(ref)) reportOrphan(`${basePath}.belongsToIcpRefs[${idx}]`, ref, 'icp');
|
|
1544
|
+
});
|
|
1545
|
+
persona.jobs.forEach((edge, idx) => {
|
|
1546
|
+
if (!jobRefs.has(edge.jobRef)) reportOrphan(`${basePath}.jobs[${idx}].jobRef`, edge.jobRef, 'job');
|
|
1547
|
+
});
|
|
1548
|
+
persona.pains.forEach((edge, idx) => {
|
|
1549
|
+
if (!painRefs.has(edge.painRef)) reportOrphan(`${basePath}.pains[${idx}].painRef`, edge.painRef, 'pain');
|
|
1550
|
+
});
|
|
1551
|
+
persona.gains.forEach((edge, idx) => {
|
|
1552
|
+
if (!gainRefs.has(edge.gainRef)) reportOrphan(`${basePath}.gains[${idx}].gainRef`, edge.gainRef, 'gain');
|
|
1553
|
+
});
|
|
1554
|
+
persona.channelRefs.forEach((ref, idx) => {
|
|
1555
|
+
if (!channelRefs.has(ref)) reportOrphan(`${basePath}.channelRefs[${idx}]`, ref, 'channel');
|
|
1556
|
+
});
|
|
1557
|
+
if (persona.preferredVoiceRef !== undefined && !voiceRefs.has(persona.preferredVoiceRef)) {
|
|
1558
|
+
reportOrphan(`${basePath}.preferredVoiceRef`, persona.preferredVoiceRef, 'voice');
|
|
1559
|
+
}
|
|
1560
|
+
}
|
|
1561
|
+
|
|
1562
|
+
// Benefits — pain/gain/job + ICP refs + cross-family feature refs +
|
|
1563
|
+
// Phase-3 proof / objection back-refs.
|
|
1564
|
+
for (const [bIdx, benefit] of snapshot.benefits.entries()) {
|
|
1565
|
+
const basePath = `benefits[${bIdx}]`;
|
|
1566
|
+
|
|
1567
|
+
benefit.relieves.forEach((edge, idx) => {
|
|
1568
|
+
if (!painRefs.has(edge.painRef)) {
|
|
1569
|
+
reportOrphan(`${basePath}.relieves[${idx}].painRef`, edge.painRef, 'pain');
|
|
1570
|
+
}
|
|
1571
|
+
});
|
|
1572
|
+
benefit.creates.forEach((edge, idx) => {
|
|
1573
|
+
if (!gainRefs.has(edge.gainRef)) {
|
|
1574
|
+
reportOrphan(`${basePath}.creates[${idx}].gainRef`, edge.gainRef, 'gain');
|
|
1575
|
+
}
|
|
1576
|
+
});
|
|
1577
|
+
benefit.advances.forEach((edge, idx) => {
|
|
1578
|
+
if (!jobRefs.has(edge.jobRef)) {
|
|
1579
|
+
reportOrphan(`${basePath}.advances[${idx}].jobRef`, edge.jobRef, 'job');
|
|
1580
|
+
}
|
|
1581
|
+
});
|
|
1582
|
+
benefit.importanceByICP.forEach((edge, idx) => {
|
|
1583
|
+
if (!icpRefs.has(edge.icpRef)) {
|
|
1584
|
+
reportOrphan(`${basePath}.importanceByICP[${idx}].icpRef`, edge.icpRef, 'icp');
|
|
1585
|
+
}
|
|
1586
|
+
});
|
|
1587
|
+
benefit.proofRefs.forEach((ref, idx) => {
|
|
1588
|
+
if (!proofRefs.has(ref)) reportOrphan(`${basePath}.proofRefs[${idx}]`, ref, 'proof');
|
|
1589
|
+
});
|
|
1590
|
+
benefit.addressesObjectionRefs.forEach((ref, idx) => {
|
|
1591
|
+
if (!objectionRefs.has(ref)) {
|
|
1592
|
+
reportOrphan(`${basePath}.addressesObjectionRefs[${idx}]`, ref, 'objection');
|
|
1593
|
+
}
|
|
1594
|
+
});
|
|
1595
|
+
|
|
1596
|
+
if (options?.availableFeatureRefs !== undefined) {
|
|
1597
|
+
benefit.deliveredByFeatureRefs.forEach((ref, idx) => {
|
|
1598
|
+
if (!options.availableFeatureRefs!.has(ref)) {
|
|
1599
|
+
reportOrphan(`${basePath}.deliveredByFeatureRefs[${idx}]`, ref, 'feature');
|
|
1600
|
+
}
|
|
1601
|
+
});
|
|
1602
|
+
}
|
|
1603
|
+
}
|
|
1604
|
+
|
|
1605
|
+
// Positionings — back to ICP + benefits + alternatives.
|
|
1606
|
+
for (const [pIdx, positioning] of snapshot.positionings.entries()) {
|
|
1607
|
+
const basePath = `positionings[${pIdx}]`;
|
|
1608
|
+
|
|
1609
|
+
if (!icpRefs.has(positioning.icpRef)) {
|
|
1610
|
+
reportOrphan(`${basePath}.icpRef`, positioning.icpRef, 'icp');
|
|
1611
|
+
}
|
|
1612
|
+
if (positioning.preferredVoiceRef !== undefined && !voiceRefs.has(positioning.preferredVoiceRef)) {
|
|
1613
|
+
reportOrphan(`${basePath}.preferredVoiceRef`, positioning.preferredVoiceRef, 'voice');
|
|
1614
|
+
}
|
|
1615
|
+
positioning.valuePillars.forEach((pillar, idx) => {
|
|
1616
|
+
pillar.backedByBenefitRefs.forEach((ref, j) => {
|
|
1617
|
+
if (!benefitRefs.has(ref)) {
|
|
1618
|
+
reportOrphan(`${basePath}.valuePillars[${idx}].backedByBenefitRefs[${j}]`, ref, 'benefit');
|
|
1619
|
+
}
|
|
1620
|
+
});
|
|
1621
|
+
});
|
|
1622
|
+
positioning.alternativesContrasted.forEach((entry, idx) => {
|
|
1623
|
+
if (!alternativeRefs.has(entry.alternativeRef)) {
|
|
1624
|
+
reportOrphan(
|
|
1625
|
+
`${basePath}.alternativesContrasted[${idx}].alternativeRef`,
|
|
1626
|
+
entry.alternativeRef,
|
|
1627
|
+
'alternative',
|
|
1628
|
+
);
|
|
1629
|
+
}
|
|
1630
|
+
});
|
|
1631
|
+
}
|
|
1632
|
+
|
|
1633
|
+
// Triggers — affected ICPs + recommended channels.
|
|
1634
|
+
for (const [tIdx, trigger] of snapshot.triggers.entries()) {
|
|
1635
|
+
const basePath = `triggers[${tIdx}]`;
|
|
1636
|
+
trigger.affectedIcpRefs.forEach((ref, idx) => {
|
|
1637
|
+
if (!icpRefs.has(ref)) reportOrphan(`${basePath}.affectedIcpRefs[${idx}]`, ref, 'icp');
|
|
1638
|
+
});
|
|
1639
|
+
trigger.recommendedChannelRefs.forEach((ref, idx) => {
|
|
1640
|
+
if (!channelRefs.has(ref)) reportOrphan(`${basePath}.recommendedChannelRefs[${idx}]`, ref, 'channel');
|
|
1641
|
+
});
|
|
1642
|
+
}
|
|
1643
|
+
|
|
1644
|
+
// Buying journeys — back to ICP.
|
|
1645
|
+
for (const [jIdx, journey] of snapshot.buyingJourneys.entries()) {
|
|
1646
|
+
const basePath = `buyingJourneys[${jIdx}]`;
|
|
1647
|
+
if (!icpRefs.has(journey.icpRef)) {
|
|
1648
|
+
reportOrphan(`${basePath}.icpRef`, journey.icpRef, 'icp');
|
|
1649
|
+
}
|
|
1650
|
+
}
|
|
1651
|
+
|
|
1652
|
+
// Proofs — supports benefits + ICPs.
|
|
1653
|
+
for (const [pIdx, proof] of snapshot.proofs.entries()) {
|
|
1654
|
+
const basePath = `proofs[${pIdx}]`;
|
|
1655
|
+
proof.supportsBenefitRefs.forEach((ref, idx) => {
|
|
1656
|
+
if (!benefitRefs.has(ref)) reportOrphan(`${basePath}.supportsBenefitRefs[${idx}]`, ref, 'benefit');
|
|
1657
|
+
});
|
|
1658
|
+
proof.supportsIcpRefs.forEach((ref, idx) => {
|
|
1659
|
+
if (!icpRefs.has(ref)) reportOrphan(`${basePath}.supportsIcpRefs[${idx}]`, ref, 'icp');
|
|
1660
|
+
});
|
|
1661
|
+
}
|
|
1662
|
+
|
|
1663
|
+
// Objections — raised by ICPs + personas, cite proofs + related benefits.
|
|
1664
|
+
for (const [oIdx, objection] of snapshot.objections.entries()) {
|
|
1665
|
+
const basePath = `objections[${oIdx}]`;
|
|
1666
|
+
objection.raisedByIcpRefs.forEach((ref, idx) => {
|
|
1667
|
+
if (!icpRefs.has(ref)) reportOrphan(`${basePath}.raisedByIcpRefs[${idx}]`, ref, 'icp');
|
|
1668
|
+
});
|
|
1669
|
+
objection.raisedByPersonaRefs.forEach((ref, idx) => {
|
|
1670
|
+
if (!personaRefs.has(ref)) reportOrphan(`${basePath}.raisedByPersonaRefs[${idx}]`, ref, 'persona');
|
|
1671
|
+
});
|
|
1672
|
+
objection.proofRefs.forEach((ref, idx) => {
|
|
1673
|
+
if (!proofRefs.has(ref)) reportOrphan(`${basePath}.proofRefs[${idx}]`, ref, 'proof');
|
|
1674
|
+
});
|
|
1675
|
+
objection.relatedBenefitRefs.forEach((ref, idx) => {
|
|
1676
|
+
if (!benefitRefs.has(ref)) reportOrphan(`${basePath}.relatedBenefitRefs[${idx}]`, ref, 'benefit');
|
|
1677
|
+
});
|
|
1678
|
+
}
|
|
1679
|
+
|
|
1680
|
+
// Message templates — Phase-2 slot, Phase-4 fill. The preferred-voice
|
|
1681
|
+
// ref MUST resolve when authored, otherwise the market generation CLI
|
|
1682
|
+
// silently falls back to the default voice and produces off-brand
|
|
1683
|
+
// copy.
|
|
1684
|
+
for (const [tIdx, template] of snapshot.messageTemplates.entries()) {
|
|
1685
|
+
const basePath = `messageTemplates[${tIdx}]`;
|
|
1686
|
+
if (template.preferredVoiceRef !== undefined && !voiceRefs.has(template.preferredVoiceRef)) {
|
|
1687
|
+
reportOrphan(`${basePath}.preferredVoiceRef`, template.preferredVoiceRef, 'voice');
|
|
1688
|
+
}
|
|
1689
|
+
}
|
|
1690
|
+
}
|
|
1691
|
+
|
|
1692
|
+
/**
|
|
1693
|
+
* D4 invariant: at most ONE THRESHOLD-classified benefit per
|
|
1694
|
+
* `(icpRef, jobRef)` cluster. THRESHOLD means "table-stakes — without
|
|
1695
|
+
* it the offer is rejected", so two competing THRESHOLDs against the
|
|
1696
|
+
* same (icp, job) means we have two unrelated table-stakes claims for
|
|
1697
|
+
* the same outcome which is structurally undefined for the FIT scorer
|
|
1698
|
+
* (`market-scoring.ts`).
|
|
1699
|
+
*
|
|
1700
|
+
* The detector dedupes per benefit by tracking the SET of benefit
|
|
1701
|
+
* `ref`s per (icp, job) — repeated `advances[]` entries on the SAME
|
|
1702
|
+
* benefit (which is itself a `DUPLICATE_EDGE_PER_ENTITY` WARN) do not
|
|
1703
|
+
* double-count and therefore do not trigger a false-positive ERROR
|
|
1704
|
+
* here. Benefits with empty `advances[]` are caught by
|
|
1705
|
+
* `THRESHOLD_BENEFIT_WITHOUT_JOB` (ERROR) — they would otherwise
|
|
1706
|
+
* structurally bypass this rule by having no (icp, job) cluster to
|
|
1707
|
+
* be counted in.
|
|
1708
|
+
*/
|
|
1709
|
+
function detectMultipleThresholdsPerIcpJob(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1710
|
+
const benefitRefsByJobByIcp = new Map<string, Map<string, Set<string>>>();
|
|
1711
|
+
|
|
1712
|
+
for (const benefit of snapshot.benefits) {
|
|
1713
|
+
const icpRefsWithThreshold = new Set(
|
|
1714
|
+
benefit.importanceByICP
|
|
1715
|
+
.filter(e => e.kanoCategory === BenefitKanoCategory.THRESHOLD)
|
|
1716
|
+
.map(e => e.icpRef),
|
|
1717
|
+
);
|
|
1718
|
+
if (icpRefsWithThreshold.size === 0) continue;
|
|
1719
|
+
|
|
1720
|
+
const distinctJobRefs = new Set(benefit.advances.map(e => e.jobRef));
|
|
1721
|
+
if (distinctJobRefs.size === 0) continue; // caught by THRESHOLD_BENEFIT_WITHOUT_JOB
|
|
1722
|
+
|
|
1723
|
+
for (const icpRef of icpRefsWithThreshold) {
|
|
1724
|
+
const byJob = benefitRefsByJobByIcp.get(icpRef) ?? new Map<string, Set<string>>();
|
|
1725
|
+
for (const jobRef of distinctJobRefs) {
|
|
1726
|
+
const set = byJob.get(jobRef) ?? new Set<string>();
|
|
1727
|
+
set.add(benefit.ref);
|
|
1728
|
+
byJob.set(jobRef, set);
|
|
1729
|
+
}
|
|
1730
|
+
benefitRefsByJobByIcp.set(icpRef, byJob);
|
|
1731
|
+
}
|
|
1732
|
+
}
|
|
1733
|
+
|
|
1734
|
+
for (const [icpRef, byJob] of benefitRefsByJobByIcp.entries()) {
|
|
1735
|
+
for (const [jobRef, refsSet] of byJob.entries()) {
|
|
1736
|
+
if (refsSet.size > 1) {
|
|
1737
|
+
const refs = [...refsSet].join(', ');
|
|
1738
|
+
issues.push({
|
|
1739
|
+
kind: MarketSnapshotIssueKind.MULTIPLE_THRESHOLDS_PER_ICP_JOB,
|
|
1740
|
+
path: `benefits.importanceByICP[icp=${icpRef}].advances[job=${jobRef}]`,
|
|
1741
|
+
message: `ICP "${icpRef}" job "${jobRef}" has multiple THRESHOLD benefits (${refs}). Only one THRESHOLD per (icp, job) cluster is allowed.`,
|
|
1742
|
+
severity: 'ERROR',
|
|
1743
|
+
});
|
|
1744
|
+
}
|
|
1745
|
+
}
|
|
1746
|
+
}
|
|
1747
|
+
}
|
|
1748
|
+
|
|
1749
|
+
/**
|
|
1750
|
+
* Companion to `MULTIPLE_THRESHOLDS_PER_ICP_JOB`. THRESHOLD is defined
|
|
1751
|
+
* as a per-(ICP, job) classification — a benefit that declares any
|
|
1752
|
+
* `kanoCategory: THRESHOLD` entry on `importanceByICP[]` MUST also
|
|
1753
|
+
* advance at least one job, otherwise the invariant has no anchor and
|
|
1754
|
+
* the FIT scorer cannot place the table-stakes claim. ERROR.
|
|
1755
|
+
*/
|
|
1756
|
+
function detectThresholdBenefitsWithoutJob(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1757
|
+
for (const [bIdx, benefit] of snapshot.benefits.entries()) {
|
|
1758
|
+
const hasThreshold = benefit.importanceByICP.some(
|
|
1759
|
+
e => e.kanoCategory === BenefitKanoCategory.THRESHOLD,
|
|
1760
|
+
);
|
|
1761
|
+
if (!hasThreshold) continue;
|
|
1762
|
+
if (benefit.advances.length > 0) continue;
|
|
1763
|
+
|
|
1764
|
+
const thresholdIcpRefs = benefit.importanceByICP
|
|
1765
|
+
.filter(e => e.kanoCategory === BenefitKanoCategory.THRESHOLD)
|
|
1766
|
+
.map(e => e.icpRef)
|
|
1767
|
+
.join(', ');
|
|
1768
|
+
issues.push({
|
|
1769
|
+
kind: MarketSnapshotIssueKind.THRESHOLD_BENEFIT_WITHOUT_JOB,
|
|
1770
|
+
path: `benefits[${bIdx}].advances`,
|
|
1771
|
+
message: `Benefit "${benefit.ref}" is THRESHOLD for ICP(s) [${thresholdIcpRefs}] but advances[] is empty. THRESHOLD is a per-(icp, job) claim — add at least one BenefitAdvancesJob entry, or downgrade kanoCategory to PERFORMANCE/DELIGHTER.`,
|
|
1772
|
+
severity: 'ERROR',
|
|
1773
|
+
});
|
|
1774
|
+
}
|
|
1775
|
+
}
|
|
1776
|
+
|
|
1777
|
+
function detectEmptyBenefitDeliveredBy(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1778
|
+
// The schema enforces `.min(1)`; this detector remains as a defence
|
|
1779
|
+
// in depth for callers that bypass parsing (legitimate scenario:
|
|
1780
|
+
// tests building snapshots with type-asserted fixtures).
|
|
1781
|
+
for (const [bIdx, benefit] of snapshot.benefits.entries()) {
|
|
1782
|
+
if (benefit.deliveredByFeatureRefs.length === 0) {
|
|
1783
|
+
issues.push({
|
|
1784
|
+
kind: MarketSnapshotIssueKind.EMPTY_BENEFIT_DELIVERED_BY,
|
|
1785
|
+
path: `benefits[${bIdx}].deliveredByFeatureRefs`,
|
|
1786
|
+
message: `Benefit "${benefit.ref}" has empty deliveredByFeatureRefs[]. A benefit must be delivered by at least one feature.`,
|
|
1787
|
+
severity: 'ERROR',
|
|
1788
|
+
});
|
|
1789
|
+
}
|
|
1790
|
+
}
|
|
1791
|
+
}
|
|
1792
|
+
|
|
1793
|
+
function detectIcpWithoutPersona(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1794
|
+
const personaParents = new Set<string>();
|
|
1795
|
+
for (const persona of snapshot.personas) {
|
|
1796
|
+
for (const ref of persona.belongsToIcpRefs) personaParents.add(ref);
|
|
1797
|
+
}
|
|
1798
|
+
|
|
1799
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
1800
|
+
if (icp.priority === ICPPriority.ANTI_TARGET) continue;
|
|
1801
|
+
if (personaParents.has(icp.ref)) continue;
|
|
1802
|
+
|
|
1803
|
+
const severity: MarketSnapshotIssueSeverity =
|
|
1804
|
+
icp.archetype === ICPArchetype.LEGAL_ENTITY ? 'ERROR' : 'WARN';
|
|
1805
|
+
issues.push({
|
|
1806
|
+
kind: MarketSnapshotIssueKind.ICP_WITHOUT_PERSONA,
|
|
1807
|
+
path: `icps[${iIdx}].ref`,
|
|
1808
|
+
message: `ICP "${icp.ref}" (archetype ${icp.archetype}) has no persona pointing at it. ${severity === 'ERROR' ? 'Required' : 'Recommended'} for ${icp.archetype}.`,
|
|
1809
|
+
severity,
|
|
1810
|
+
});
|
|
1811
|
+
}
|
|
1812
|
+
}
|
|
1813
|
+
|
|
1814
|
+
function detectInfluenceCycles(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1815
|
+
// Self-loops first — always ERROR.
|
|
1816
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
1817
|
+
icp.influences.forEach((edge, idx) => {
|
|
1818
|
+
if (edge.icpRef === icp.ref) {
|
|
1819
|
+
issues.push({
|
|
1820
|
+
kind: MarketSnapshotIssueKind.INFLUENCE_CYCLE,
|
|
1821
|
+
path: `icps[${iIdx}].influences[${idx}].icpRef`,
|
|
1822
|
+
message: `ICP "${icp.ref}" has a self-loop in influences[]. Self-loops are not allowed.`,
|
|
1823
|
+
severity: 'ERROR',
|
|
1824
|
+
});
|
|
1825
|
+
}
|
|
1826
|
+
});
|
|
1827
|
+
}
|
|
1828
|
+
|
|
1829
|
+
// Multi-node cycles — Tarjan-style SCC scan, report each cycle once.
|
|
1830
|
+
const adjacency = new Map<string, string[]>();
|
|
1831
|
+
for (const icp of snapshot.icps) {
|
|
1832
|
+
adjacency.set(
|
|
1833
|
+
icp.ref,
|
|
1834
|
+
icp.influences.filter(e => e.icpRef !== icp.ref).map(e => e.icpRef),
|
|
1835
|
+
);
|
|
1836
|
+
}
|
|
1837
|
+
|
|
1838
|
+
const seenCycles = new Set<string>();
|
|
1839
|
+
const visited = new Set<string>();
|
|
1840
|
+
|
|
1841
|
+
for (const startRef of adjacency.keys()) {
|
|
1842
|
+
if (visited.has(startRef)) continue;
|
|
1843
|
+
const stack: string[] = [];
|
|
1844
|
+
const onStack = new Set<string>();
|
|
1845
|
+
|
|
1846
|
+
const dfs = (node: string): void => {
|
|
1847
|
+
visited.add(node);
|
|
1848
|
+
stack.push(node);
|
|
1849
|
+
onStack.add(node);
|
|
1850
|
+
|
|
1851
|
+
for (const next of adjacency.get(node) ?? []) {
|
|
1852
|
+
if (!adjacency.has(next)) continue;
|
|
1853
|
+
if (!visited.has(next)) {
|
|
1854
|
+
dfs(next);
|
|
1855
|
+
} else if (onStack.has(next)) {
|
|
1856
|
+
const cycleStart = stack.indexOf(next);
|
|
1857
|
+
if (cycleStart >= 0) {
|
|
1858
|
+
const cycle = stack.slice(cycleStart);
|
|
1859
|
+
const key = [...cycle].sort().join('|');
|
|
1860
|
+
if (!seenCycles.has(key)) {
|
|
1861
|
+
seenCycles.add(key);
|
|
1862
|
+
issues.push({
|
|
1863
|
+
kind: MarketSnapshotIssueKind.INFLUENCE_CYCLE,
|
|
1864
|
+
path: `icps[*].influences`,
|
|
1865
|
+
message: `Influence cycle detected: ${cycle.join(' → ')} → ${next}. Cycles are accepted but emit a WARN.`,
|
|
1866
|
+
severity: 'WARN',
|
|
1867
|
+
});
|
|
1868
|
+
}
|
|
1869
|
+
}
|
|
1870
|
+
}
|
|
1871
|
+
}
|
|
1872
|
+
|
|
1873
|
+
stack.pop();
|
|
1874
|
+
onStack.delete(node);
|
|
1875
|
+
};
|
|
1876
|
+
|
|
1877
|
+
dfs(startRef);
|
|
1878
|
+
}
|
|
1879
|
+
}
|
|
1880
|
+
|
|
1881
|
+
function detectMissingPositioningForIcp(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1882
|
+
const positionedIcpRefs = new Set(snapshot.positionings.map(p => p.icpRef));
|
|
1883
|
+
|
|
1884
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
1885
|
+
if (icp.priority !== ICPPriority.CORE && icp.priority !== ICPPriority.EXPANSION) continue;
|
|
1886
|
+
if (positionedIcpRefs.has(icp.ref)) continue;
|
|
1887
|
+
|
|
1888
|
+
issues.push({
|
|
1889
|
+
kind: MarketSnapshotIssueKind.MISSING_POSITIONING_FOR_ICP,
|
|
1890
|
+
path: `icps[${iIdx}].ref`,
|
|
1891
|
+
message: `ICP "${icp.ref}" has priority ${icp.priority} but no MarketPositioning entry. CORE and EXPANSION ICPs must be positioned.`,
|
|
1892
|
+
severity: 'ERROR',
|
|
1893
|
+
});
|
|
1894
|
+
}
|
|
1895
|
+
}
|
|
1896
|
+
|
|
1897
|
+
const REVIEW_CADENCE_TO_DAYS: Record<ReviewCadence, number> = {
|
|
1898
|
+
[ReviewCadence.WEEKLY]: 7,
|
|
1899
|
+
[ReviewCadence.MONTHLY]: 31,
|
|
1900
|
+
[ReviewCadence.QUARTERLY]: 92,
|
|
1901
|
+
[ReviewCadence.YEARLY]: 366,
|
|
1902
|
+
[ReviewCadence.AS_NEEDED]: Number.POSITIVE_INFINITY,
|
|
1903
|
+
};
|
|
1904
|
+
|
|
1905
|
+
function detectStaleAuthored(
|
|
1906
|
+
snapshot: MarketSnapshot,
|
|
1907
|
+
now: Date,
|
|
1908
|
+
issues: MarketSnapshotIssue[],
|
|
1909
|
+
): void {
|
|
1910
|
+
const checkAuthored = (authored: MarketAuthoredMetadata | undefined, path: string, ref: string): void => {
|
|
1911
|
+
if (authored?.reviewCadence === undefined) return;
|
|
1912
|
+
const days = REVIEW_CADENCE_TO_DAYS[authored.reviewCadence];
|
|
1913
|
+
if (!Number.isFinite(days)) return;
|
|
1914
|
+
const lastAuthored = new Date(authored.lastAuthoredAt).getTime();
|
|
1915
|
+
if (Number.isNaN(lastAuthored)) return;
|
|
1916
|
+
const ageMs = now.getTime() - lastAuthored;
|
|
1917
|
+
const ageDays = ageMs / (24 * 60 * 60 * 1000);
|
|
1918
|
+
if (ageDays > days) {
|
|
1919
|
+
issues.push({
|
|
1920
|
+
kind: MarketSnapshotIssueKind.STALE_AUTHORED,
|
|
1921
|
+
path,
|
|
1922
|
+
message: `Authored content for "${ref}" is ${Math.floor(ageDays)} days old (cadence ${authored.reviewCadence} ⇒ ${days}d). Re-author or remove the cadence.`,
|
|
1923
|
+
severity: 'WARN',
|
|
1924
|
+
});
|
|
1925
|
+
}
|
|
1926
|
+
};
|
|
1927
|
+
|
|
1928
|
+
snapshot.icps.forEach((icp, idx) => checkAuthored(icp.authored, `icps[${idx}].authored`, icp.ref));
|
|
1929
|
+
snapshot.personas.forEach((p, idx) => checkAuthored(p.authored, `personas[${idx}].authored`, p.ref));
|
|
1930
|
+
snapshot.jobs.forEach((j, idx) => checkAuthored(j.authored, `jobs[${idx}].authored`, j.ref));
|
|
1931
|
+
snapshot.pains.forEach((p, idx) => checkAuthored(p.authored, `pains[${idx}].authored`, p.ref));
|
|
1932
|
+
snapshot.gains.forEach((g, idx) => checkAuthored(g.authored, `gains[${idx}].authored`, g.ref));
|
|
1933
|
+
snapshot.tonesOfVoice.forEach((v, idx) => checkAuthored(v.authored, `tonesOfVoice[${idx}].authored`, v.ref));
|
|
1934
|
+
snapshot.benefits.forEach((b, idx) => checkAuthored(b.authored, `benefits[${idx}].authored`, b.ref));
|
|
1935
|
+
snapshot.positionings.forEach((p, idx) => checkAuthored(p.authored, `positionings[${idx}].authored`, p.ref));
|
|
1936
|
+
snapshot.messageTemplates.forEach((t, idx) => checkAuthored(t.authored, `messageTemplates[${idx}].authored`, t.ref));
|
|
1937
|
+
snapshot.channels.forEach((c, idx) => checkAuthored(c.authored, `channels[${idx}].authored`, c.ref));
|
|
1938
|
+
snapshot.alternatives.forEach((a, idx) => checkAuthored(a.authored, `alternatives[${idx}].authored`, a.ref));
|
|
1939
|
+
snapshot.triggers.forEach((t, idx) => checkAuthored(t.authored, `triggers[${idx}].authored`, t.ref));
|
|
1940
|
+
snapshot.buyingJourneys.forEach((j, idx) => checkAuthored(j.authored, `buyingJourneys[${idx}].authored`, j.ref));
|
|
1941
|
+
snapshot.proofs.forEach((p, idx) => checkAuthored(p.authored, `proofs[${idx}].authored`, p.ref));
|
|
1942
|
+
snapshot.objections.forEach((o, idx) => checkAuthored(o.authored, `objections[${idx}].authored`, o.ref));
|
|
1943
|
+
checkAuthored(snapshot.category.authored, 'category.authored', snapshot.category.ref);
|
|
1944
|
+
}
|
|
1945
|
+
|
|
1946
|
+
/**
|
|
1947
|
+
* Per-entity duplicate-edge detection.
|
|
1948
|
+
*
|
|
1949
|
+
* Scope (intentionally bounded — see `DUPLICATE_EDGE_PER_ENTITY` JSDoc
|
|
1950
|
+
* on the enum for the canonical list):
|
|
1951
|
+
* - ICP and persona `pains[].painRef` / `gains[].gainRef` /
|
|
1952
|
+
* `jobs[].jobRef`. Duplicates here are typically the result of an
|
|
1953
|
+
* `inheritFrom(parentIcp)` spread followed by a forgotten
|
|
1954
|
+
* `.filter()` step on the persona.
|
|
1955
|
+
* - Benefit `importanceByICP[].icpRef`. Duplicates make per-ICP
|
|
1956
|
+
* weighting non-deterministic in the FIT scorer (the last one wins
|
|
1957
|
+
* silently). We deliberately do NOT collapse the duplicates — we
|
|
1958
|
+
* surface them so authors fix the source instead of relying on
|
|
1959
|
+
* detector-side normalization.
|
|
1960
|
+
*
|
|
1961
|
+
* NOT covered (other detectors / schema constraints handle these):
|
|
1962
|
+
* - benefit `relieves` / `creates` / `advances` weighted edges — the
|
|
1963
|
+
* degree might legitimately differ across entries; future work.
|
|
1964
|
+
* - ICP `buyingGroup[].personaRef` — deduplication is enforced by
|
|
1965
|
+
* intent (a persona is in the group exactly once); future work.
|
|
1966
|
+
*/
|
|
1967
|
+
function detectDuplicateEdgesPerEntity(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
1968
|
+
const reportDuplicates = (
|
|
1969
|
+
refs: string[],
|
|
1970
|
+
basePath: string,
|
|
1971
|
+
field: string,
|
|
1972
|
+
ownerRef: string,
|
|
1973
|
+
refSubpath: string = '',
|
|
1974
|
+
hint: string = 'Likely an inheritFrom() spread that wasn\'t deduplicated.',
|
|
1975
|
+
): void => {
|
|
1976
|
+
const seen = new Set<string>();
|
|
1977
|
+
refs.forEach((ref, idx) => {
|
|
1978
|
+
if (seen.has(ref)) {
|
|
1979
|
+
issues.push({
|
|
1980
|
+
kind: MarketSnapshotIssueKind.DUPLICATE_EDGE_PER_ENTITY,
|
|
1981
|
+
path: `${basePath}.${field}[${idx}]${refSubpath}`,
|
|
1982
|
+
message: `${field} ref "${ref}" appears more than once on "${ownerRef}". ${hint}`,
|
|
1983
|
+
severity: 'WARN',
|
|
1984
|
+
});
|
|
1985
|
+
}
|
|
1986
|
+
seen.add(ref);
|
|
1987
|
+
});
|
|
1988
|
+
};
|
|
1989
|
+
|
|
1990
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
1991
|
+
const basePath = `icps[${iIdx}]`;
|
|
1992
|
+
reportDuplicates(icp.pains.map(e => e.painRef), basePath, 'pains', icp.ref, '.painRef');
|
|
1993
|
+
reportDuplicates(icp.gains.map(e => e.gainRef), basePath, 'gains', icp.ref, '.gainRef');
|
|
1994
|
+
reportDuplicates(icp.jobs.map(e => e.jobRef), basePath, 'jobs', icp.ref, '.jobRef');
|
|
1995
|
+
}
|
|
1996
|
+
for (const [pIdx, persona] of snapshot.personas.entries()) {
|
|
1997
|
+
const basePath = `personas[${pIdx}]`;
|
|
1998
|
+
reportDuplicates(persona.pains.map(e => e.painRef), basePath, 'pains', persona.ref, '.painRef');
|
|
1999
|
+
reportDuplicates(persona.gains.map(e => e.gainRef), basePath, 'gains', persona.ref, '.gainRef');
|
|
2000
|
+
reportDuplicates(persona.jobs.map(e => e.jobRef), basePath, 'jobs', persona.ref, '.jobRef');
|
|
2001
|
+
}
|
|
2002
|
+
for (const [bIdx, benefit] of snapshot.benefits.entries()) {
|
|
2003
|
+
const basePath = `benefits[${bIdx}]`;
|
|
2004
|
+
reportDuplicates(
|
|
2005
|
+
benefit.importanceByICP.map(e => e.icpRef),
|
|
2006
|
+
basePath,
|
|
2007
|
+
'importanceByICP',
|
|
2008
|
+
benefit.ref,
|
|
2009
|
+
'.icpRef',
|
|
2010
|
+
'Each (benefit, icp) pair must appear at most once — duplicates make per-ICP weighting non-deterministic.',
|
|
2011
|
+
);
|
|
2012
|
+
}
|
|
2013
|
+
}
|
|
2014
|
+
|
|
2015
|
+
function detectInvalidAntiTargetPurposeMix(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2016
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
2017
|
+
if (icp.priority !== ICPPriority.ANTI_TARGET) continue;
|
|
2018
|
+
const isZero = icp.purposeMix.adoption === 0 && icp.purposeMix.revenue === 0;
|
|
2019
|
+
if (isZero) continue;
|
|
2020
|
+
issues.push({
|
|
2021
|
+
kind: MarketSnapshotIssueKind.INVALID_ANTI_TARGET_PURPOSE_MIX,
|
|
2022
|
+
path: `icps[${iIdx}].purposeMix`,
|
|
2023
|
+
message: `ICP "${icp.ref}" has priority ANTI_TARGET but purposeMix=${JSON.stringify(icp.purposeMix)}. ANTI_TARGET ICPs MUST carry { adoption: 0, revenue: 0 }.`,
|
|
2024
|
+
severity: 'ERROR',
|
|
2025
|
+
});
|
|
2026
|
+
}
|
|
2027
|
+
}
|
|
2028
|
+
|
|
2029
|
+
function detectBuyingGroupPersonasMissingDmuRole(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2030
|
+
for (const [pIdx, persona] of snapshot.personas.entries()) {
|
|
2031
|
+
if (persona.personaScope !== PersonaScope.BUYING_GROUP_MEMBER) continue;
|
|
2032
|
+
if (persona.dmuRole !== undefined) continue;
|
|
2033
|
+
issues.push({
|
|
2034
|
+
kind: MarketSnapshotIssueKind.BUYING_GROUP_PERSONA_MISSING_DMU_ROLE,
|
|
2035
|
+
path: `personas[${pIdx}].dmuRole`,
|
|
2036
|
+
message: `Persona "${persona.ref}" has personaScope BUYING_GROUP_MEMBER but no dmuRole. DMU role is required for buying-group members.`,
|
|
2037
|
+
severity: 'ERROR',
|
|
2038
|
+
});
|
|
2039
|
+
}
|
|
2040
|
+
}
|
|
2041
|
+
|
|
2042
|
+
/**
|
|
2043
|
+
* The ICP→persona buying-group link MUST be symmetric: when an ICP
|
|
2044
|
+
* lists a persona in `buyingGroup[].personaRef`, the persona's
|
|
2045
|
+
* `belongsToIcpRefs[]` MUST contain the ICP. Asymmetric links cause
|
|
2046
|
+
* downstream consumers (DMU rendering, persona-by-ICP indexing,
|
|
2047
|
+
* market generation targeting) to silently drop the persona because
|
|
2048
|
+
* the `belongsToIcpRefs[]` index is the canonical traversal path.
|
|
2049
|
+
*
|
|
2050
|
+
* ERROR severity — this is a structural integrity bug, not authoring
|
|
2051
|
+
* polish: the snapshot will pass parse + intent but will silently
|
|
2052
|
+
* misbehave at runtime.
|
|
2053
|
+
*
|
|
2054
|
+
* Reverse direction (persona declares an ICP that does NOT list the
|
|
2055
|
+
* persona in its `buyingGroup[]`) is intentionally NOT reported here:
|
|
2056
|
+
* personas of `INDIVIDUAL_SELF` / `INDIVIDUAL_INFLUENCER` scope are
|
|
2057
|
+
* legitimately attached to ICPs that have no formal buying group.
|
|
2058
|
+
* The detector only runs the ICP→persona direction.
|
|
2059
|
+
*/
|
|
2060
|
+
function detectBuyingGroupBacklinkMissing(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2061
|
+
const personasByRef = new Map(snapshot.personas.map(p => [p.ref, p] as const));
|
|
2062
|
+
|
|
2063
|
+
for (const [iIdx, icp] of snapshot.icps.entries()) {
|
|
2064
|
+
icp.buyingGroup.forEach((entry, idx) => {
|
|
2065
|
+
const persona = personasByRef.get(entry.personaRef);
|
|
2066
|
+
if (persona === undefined) return; // orphan caught elsewhere
|
|
2067
|
+
if (persona.belongsToIcpRefs.includes(icp.ref)) return;
|
|
2068
|
+
issues.push({
|
|
2069
|
+
kind: MarketSnapshotIssueKind.BUYING_GROUP_BACKLINK_MISSING,
|
|
2070
|
+
path: `icps[${iIdx}].buyingGroup[${idx}].personaRef`,
|
|
2071
|
+
message: `ICP "${icp.ref}" lists persona "${persona.ref}" in buyingGroup[], but the persona's belongsToIcpRefs[] is ${JSON.stringify(persona.belongsToIcpRefs)} (does not include "${icp.ref}"). The link must be symmetric.`,
|
|
2072
|
+
severity: 'ERROR',
|
|
2073
|
+
});
|
|
2074
|
+
});
|
|
2075
|
+
}
|
|
2076
|
+
}
|
|
2077
|
+
|
|
2078
|
+
/**
|
|
2079
|
+
* Phase 3 — a `MarketProof` that supports neither a benefit nor an ICP
|
|
2080
|
+
* has no place to land in generated copy. WARN, not ERROR — the proof
|
|
2081
|
+
* may be in flight ("about to wire it up next") and should not block
|
|
2082
|
+
* boot.
|
|
2083
|
+
*/
|
|
2084
|
+
function detectProofsWithoutSupport(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2085
|
+
for (const [pIdx, proof] of snapshot.proofs.entries()) {
|
|
2086
|
+
if (proof.supportsBenefitRefs.length > 0 || proof.supportsIcpRefs.length > 0) continue;
|
|
2087
|
+
issues.push({
|
|
2088
|
+
kind: MarketSnapshotIssueKind.PROOF_WITHOUT_SUPPORT,
|
|
2089
|
+
path: `proofs[${pIdx}]`,
|
|
2090
|
+
message: `Proof "${proof.ref}" supports neither a benefit nor an ICP. Add at least one supportsBenefitRefs[] or supportsIcpRefs[] entry, or remove the proof.`,
|
|
2091
|
+
severity: 'WARN',
|
|
2092
|
+
});
|
|
2093
|
+
}
|
|
2094
|
+
}
|
|
2095
|
+
|
|
2096
|
+
/**
|
|
2097
|
+
* Phase 3 — proofKind/payload coherence (WARN). The schema is
|
|
2098
|
+
* intentionally permissive (both `attribution` and `metric` are
|
|
2099
|
+
* optional on every kind) so that authors can mix proof shapes
|
|
2100
|
+
* without fighting the type system. This detector flags the two
|
|
2101
|
+
* mismatches that are unambiguously authoring drift:
|
|
2102
|
+
*
|
|
2103
|
+
* 1. `METRIC` proof without a `metric` block — the structured
|
|
2104
|
+
* `value + unit + period` payload is what distinguishes a
|
|
2105
|
+
* `METRIC` proof from a `QUOTE` that happens to carry a number.
|
|
2106
|
+
* Without it the rendering layer cannot format the proof as a
|
|
2107
|
+
* metric (no value to surface, no unit to localize). Authors
|
|
2108
|
+
* should either add the `metric` block or downgrade the kind to
|
|
2109
|
+
* `QUOTE` / `CASE_STUDY`.
|
|
2110
|
+
* 2. `LOGO` proof with a `metric` block — a logo carries no
|
|
2111
|
+
* quantitative payload by definition, so a `metric` block on a
|
|
2112
|
+
* `LOGO` is a category error. Either move the metric to a
|
|
2113
|
+
* sibling `METRIC` proof or change the kind.
|
|
2114
|
+
*
|
|
2115
|
+
* All other kind/payload combinations are deliberately accepted:
|
|
2116
|
+
* a `QUOTE` may carry a `metric` (a quote that quantifies an
|
|
2117
|
+
* outcome), an `AWARD` may carry an `attribution` (the awarding
|
|
2118
|
+
* body), etc. Adding more rules here trades flexibility for
|
|
2119
|
+
* marginal signal — keep this conservative.
|
|
2120
|
+
*/
|
|
2121
|
+
function detectProofKindPayloadMismatch(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2122
|
+
for (const [pIdx, proof] of snapshot.proofs.entries()) {
|
|
2123
|
+
if (proof.proofKind === ProofKind.METRIC && proof.metric === undefined) {
|
|
2124
|
+
issues.push({
|
|
2125
|
+
kind: MarketSnapshotIssueKind.PROOF_KIND_PAYLOAD_MISMATCH,
|
|
2126
|
+
path: `proofs[${pIdx}].metric`,
|
|
2127
|
+
message: `Proof "${proof.ref}" is METRIC but carries no structured \`metric\` block (value + unit). Add the metric block or downgrade proofKind to QUOTE/CASE_STUDY.`,
|
|
2128
|
+
severity: 'WARN',
|
|
2129
|
+
});
|
|
2130
|
+
}
|
|
2131
|
+
if (proof.proofKind === ProofKind.LOGO && proof.metric !== undefined) {
|
|
2132
|
+
issues.push({
|
|
2133
|
+
kind: MarketSnapshotIssueKind.PROOF_KIND_PAYLOAD_MISMATCH,
|
|
2134
|
+
path: `proofs[${pIdx}].metric`,
|
|
2135
|
+
message: `Proof "${proof.ref}" is LOGO but carries a \`metric\` block. A logo has no quantitative payload — move the metric to a sibling METRIC proof or change the proofKind.`,
|
|
2136
|
+
severity: 'WARN',
|
|
2137
|
+
});
|
|
2138
|
+
}
|
|
2139
|
+
}
|
|
2140
|
+
}
|
|
2141
|
+
|
|
2142
|
+
/**
|
|
2143
|
+
* A `MarketBuyingJourney` listing the same `BuyingJourneyStage` enum
|
|
2144
|
+
* value more than once is a structural authoring bug (which entry
|
|
2145
|
+
* wins for prompt enrichment? non-deterministic). ERROR.
|
|
2146
|
+
*/
|
|
2147
|
+
function detectDuplicateJourneyStages(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2148
|
+
for (const [jIdx, journey] of snapshot.buyingJourneys.entries()) {
|
|
2149
|
+
const seenStages = new Set<string>();
|
|
2150
|
+
journey.stages.forEach((entry, idx) => {
|
|
2151
|
+
if (seenStages.has(entry.stage)) {
|
|
2152
|
+
issues.push({
|
|
2153
|
+
kind: MarketSnapshotIssueKind.DUPLICATE_JOURNEY_STAGE,
|
|
2154
|
+
path: `buyingJourneys[${jIdx}].stages[${idx}].stage`,
|
|
2155
|
+
message: `Buying journey "${journey.ref}" lists stage ${entry.stage} more than once. Each BuyingJourneyStage may appear at most once per journey.`,
|
|
2156
|
+
severity: 'ERROR',
|
|
2157
|
+
});
|
|
2158
|
+
}
|
|
2159
|
+
seenStages.add(entry.stage);
|
|
2160
|
+
});
|
|
2161
|
+
}
|
|
2162
|
+
}
|
|
2163
|
+
|
|
2164
|
+
/**
|
|
2165
|
+
* Two `MarketBuyingJourney` entries pointing at the same `icpRef` is
|
|
2166
|
+
* a structural authoring bug — the model is "one journey per ICP" and
|
|
2167
|
+
* downstream consumers (prompt enrichment, journey-by-ICP indexing)
|
|
2168
|
+
* will silently pick the first match. ERROR.
|
|
2169
|
+
*/
|
|
2170
|
+
function detectDuplicateBuyingJourneyForIcp(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2171
|
+
const seenIcpRefs = new Map<string, number>();
|
|
2172
|
+
snapshot.buyingJourneys.forEach((journey, idx) => {
|
|
2173
|
+
const previousIdx = seenIcpRefs.get(journey.icpRef);
|
|
2174
|
+
if (previousIdx !== undefined) {
|
|
2175
|
+
issues.push({
|
|
2176
|
+
kind: MarketSnapshotIssueKind.DUPLICATE_BUYING_JOURNEY_FOR_ICP,
|
|
2177
|
+
path: `buyingJourneys[${idx}].icpRef`,
|
|
2178
|
+
message: `Buying journey "${journey.ref}" targets ICP "${journey.icpRef}" but buyingJourneys[${previousIdx}] already targets the same ICP. The model is one journey per ICP — merge or remove one.`,
|
|
2179
|
+
severity: 'ERROR',
|
|
2180
|
+
});
|
|
2181
|
+
return;
|
|
2182
|
+
}
|
|
2183
|
+
seenIcpRefs.set(journey.icpRef, idx);
|
|
2184
|
+
});
|
|
2185
|
+
}
|
|
2186
|
+
|
|
2187
|
+
/**
|
|
2188
|
+
* Semantic check: an objection citing `proofRefs[]` should point at
|
|
2189
|
+
* proofs whose support set actually intersects the objection's claim.
|
|
2190
|
+
*
|
|
2191
|
+
* Both sides of the intersection are unioned to be permissive without
|
|
2192
|
+
* being toothless:
|
|
2193
|
+
* - Proof support side: `proof.supportsBenefitRefs[]` ∪
|
|
2194
|
+
* `proof.supportsIcpRefs[]`. A proof that supports the ICP raising
|
|
2195
|
+
* the objection (e.g. a `LOGO` proof for that ICP) is considered
|
|
2196
|
+
* to back the objection even if it doesn't directly back a specific
|
|
2197
|
+
* benefit — logos and case studies are rarely benefit-scoped.
|
|
2198
|
+
* - Objection target side: `objection.relatedBenefitRefs[]` ∪
|
|
2199
|
+
* `objection.raisedByIcpRefs[]`.
|
|
2200
|
+
*
|
|
2201
|
+
* WARN (authoring drift, not catastrophic — the spec parses, but the
|
|
2202
|
+
* cited proofs will not render as supporting evidence in any of the
|
|
2203
|
+
* downstream prompt blocks). Orphan refs are caught separately by
|
|
2204
|
+
* `detectOrphanRefs`.
|
|
2205
|
+
*
|
|
2206
|
+
* Skipped for objections where either side of the intersection is
|
|
2207
|
+
* empty (no proofs cited OR neither related benefits nor raising ICPs
|
|
2208
|
+
* authored — the check has no signal then).
|
|
2209
|
+
*/
|
|
2210
|
+
function detectObjectionProofBenefitMismatch(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
|
|
2211
|
+
const proofsByRef = new Map(snapshot.proofs.map(p => [p.ref, p] as const));
|
|
2212
|
+
|
|
2213
|
+
for (const [oIdx, objection] of snapshot.objections.entries()) {
|
|
2214
|
+
if (objection.proofRefs.length === 0) continue;
|
|
2215
|
+
const objectionTargets = new Set<string>([
|
|
2216
|
+
...objection.relatedBenefitRefs,
|
|
2217
|
+
...objection.raisedByIcpRefs,
|
|
2218
|
+
]);
|
|
2219
|
+
if (objectionTargets.size === 0) continue;
|
|
2220
|
+
|
|
2221
|
+
const supported = new Set<string>();
|
|
2222
|
+
for (const proofRef of objection.proofRefs) {
|
|
2223
|
+
const proof = proofsByRef.get(proofRef);
|
|
2224
|
+
if (proof === undefined) continue; // orphan caught elsewhere
|
|
2225
|
+
for (const benefitRef of proof.supportsBenefitRefs) supported.add(benefitRef);
|
|
2226
|
+
for (const icpRef of proof.supportsIcpRefs) supported.add(icpRef);
|
|
2227
|
+
}
|
|
2228
|
+
|
|
2229
|
+
const intersects = [...objectionTargets].some(ref => supported.has(ref));
|
|
2230
|
+
if (intersects) continue;
|
|
2231
|
+
|
|
2232
|
+
issues.push({
|
|
2233
|
+
kind: MarketSnapshotIssueKind.OBJECTION_PROOF_BENEFIT_MISMATCH,
|
|
2234
|
+
path: `objections[${oIdx}].proofRefs`,
|
|
2235
|
+
message: `Objection "${objection.ref}" cites proofRefs ${JSON.stringify(objection.proofRefs)} but none of them supports any benefit in relatedBenefitRefs ${JSON.stringify(objection.relatedBenefitRefs)} nor any ICP in raisedByIcpRefs ${JSON.stringify(objection.raisedByIcpRefs)}. The cited proofs do not back the objection.`,
|
|
2236
|
+
severity: 'WARN',
|
|
2237
|
+
});
|
|
2238
|
+
}
|
|
2239
|
+
}
|
|
2240
|
+
|
|
2241
|
+
/**
|
|
2242
|
+
* Maps a `MarketMessageRequiredInput` enum value to the placeholder
|
|
2243
|
+
* shapes inside `promptTemplate` that consume it. Each input matches
|
|
2244
|
+
* either the bare `{{<value>}}` token or any dotted-property descent
|
|
2245
|
+
* `{{<entityName>.path}}` (e.g. `icpRef` is consumed by `{{icpRef}}`,
|
|
2246
|
+
* `{{icp.name}}`, `{{icp.profile.geographies}}`).
|
|
2247
|
+
*
|
|
2248
|
+
* The `entityName` form is the camelCase root WITHOUT the trailing
|
|
2249
|
+
* `Ref` suffix — i.e. `icpRef` → entity name `icp`, `benefitRef` →
|
|
2250
|
+
* `benefit`. This matches the conventional Mustache shape authors use
|
|
2251
|
+
* in templates ("ICP context surfaces under `icp.*`").
|
|
2252
|
+
*/
|
|
2253
|
+
const REQUIRED_INPUT_PLACEHOLDER_PATTERNS: Record<MarketMessageRequiredInput, RegExp> = {
|
|
2254
|
+
[MarketMessageRequiredInput.ICP_REF]: /\{\{\s*(?:icpRef|icp(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
|
|
2255
|
+
[MarketMessageRequiredInput.BENEFIT_REF]: /\{\{\s*(?:benefitRef|benefit(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
|
|
2256
|
+
[MarketMessageRequiredInput.CHANNEL_REF]: /\{\{\s*(?:channelRef|channel(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
|
|
2257
|
+
[MarketMessageRequiredInput.OBJECTION_REF]: /\{\{\s*(?:objectionRef|objection(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
|
|
2258
|
+
};
|
|
2259
|
+
|
|
2260
|
+
/**
|
|
2261
|
+
* Inverse of `REQUIRED_INPUT_PLACEHOLDER_PATTERNS` — given a Mustache
|
|
2262
|
+
* placeholder name extracted from a template body, return the
|
|
2263
|
+
* `MarketMessageRequiredInput` it consumes (or `undefined` if the
|
|
2264
|
+
* leading token is the exempt `{{output_language}}` / an unknown
|
|
2265
|
+
* camelCase root).
|
|
2266
|
+
*
|
|
2267
|
+
* Keyed on the **leading entity name** in two distinct shapes:
|
|
2268
|
+
* - the dotted-root entity (`icp` → consumed by `{{icp.name}}`,
|
|
2269
|
+
* `{{icp.profile.…}}`);
|
|
2270
|
+
* - the explicit `<entity>Ref` token (`icpRef` → consumed by
|
|
2271
|
+
* `{{icpRef}}`).
|
|
2272
|
+
*
|
|
2273
|
+
* The bare-entity token `{{icp}}` (no dot, no `Ref` suffix) is
|
|
2274
|
+
* intentionally NOT a recognized form here: Direction-1 of the
|
|
2275
|
+
* validator (declared → used) rejects it (the regex requires
|
|
2276
|
+
* `\{\{icpRef\}\}` OR `\{\{icp\.<segment>\}\}`), so accepting it in
|
|
2277
|
+
* Direction-2 would create an asymmetric false-positive WARN. The
|
|
2278
|
+
* detector enforces this in `isRecognizedPlaceholderToken(...)`
|
|
2279
|
+
* before consulting the map.
|
|
2280
|
+
*/
|
|
2281
|
+
const PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT: Record<string, MarketMessageRequiredInput> = {
|
|
2282
|
+
icp: MarketMessageRequiredInput.ICP_REF,
|
|
2283
|
+
icpRef: MarketMessageRequiredInput.ICP_REF,
|
|
2284
|
+
benefit: MarketMessageRequiredInput.BENEFIT_REF,
|
|
2285
|
+
benefitRef: MarketMessageRequiredInput.BENEFIT_REF,
|
|
2286
|
+
channel: MarketMessageRequiredInput.CHANNEL_REF,
|
|
2287
|
+
channelRef: MarketMessageRequiredInput.CHANNEL_REF,
|
|
2288
|
+
objection: MarketMessageRequiredInput.OBJECTION_REF,
|
|
2289
|
+
objectionRef: MarketMessageRequiredInput.OBJECTION_REF,
|
|
2290
|
+
};
|
|
2291
|
+
|
|
2292
|
+
/**
|
|
2293
|
+
* Returns the `MarketMessageRequiredInput` consumed by a Mustache
|
|
2294
|
+
* placeholder body (everything between `{{` and `}}` with whitespace
|
|
2295
|
+
* stripped), or `undefined` when the token does not consume any
|
|
2296
|
+
* required input.
|
|
2297
|
+
*
|
|
2298
|
+
* Symmetric with `REQUIRED_INPUT_PLACEHOLDER_PATTERNS`:
|
|
2299
|
+
* - dotted access (`icp.name`, `icp.profile.geographies`) → consumes
|
|
2300
|
+
* the dotted root's required input;
|
|
2301
|
+
* - explicit `<entity>Ref` (`icpRef`) → consumes the matching
|
|
2302
|
+
* required input;
|
|
2303
|
+
* - bare entity (`icp`) → DOES NOT consume — same as Direction-1.
|
|
2304
|
+
*/
|
|
2305
|
+
function lookupConsumedRequiredInput(
|
|
2306
|
+
innerExpression: string,
|
|
2307
|
+
): MarketMessageRequiredInput | undefined {
|
|
2308
|
+
const dotIndex = innerExpression.indexOf('.');
|
|
2309
|
+
if (dotIndex >= 0) {
|
|
2310
|
+
const dottedRoot = innerExpression.slice(0, dotIndex).trim();
|
|
2311
|
+
return PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT[dottedRoot];
|
|
2312
|
+
}
|
|
2313
|
+
// No dot — only the explicit `<entity>Ref` form is recognized.
|
|
2314
|
+
if (!innerExpression.endsWith('Ref')) return undefined;
|
|
2315
|
+
return PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT[innerExpression];
|
|
2316
|
+
}
|
|
2317
|
+
|
|
2318
|
+
/**
|
|
2319
|
+
* Mustache token names that are CLI-injected at render time and are
|
|
2320
|
+
* therefore NOT expected to appear in `requiredInputs[]`. Today only
|
|
2321
|
+
* `output_language` is in this set (substituted from the
|
|
2322
|
+
* `--output-language` flag), but the set
|
|
2323
|
+
* is structured to grow with future CLI-side affordances.
|
|
2324
|
+
*/
|
|
2325
|
+
const PLACEHOLDER_ENTITY_EXEMPT_FROM_REQUIRED_INPUTS: ReadonlySet<string> = new Set([
|
|
2326
|
+
'output_language',
|
|
2327
|
+
]);
|
|
2328
|
+
|
|
2329
|
+
/**
|
|
2330
|
+
* Match every Mustache placeholder inside a template body. Captures
|
|
2331
|
+
* the inner expression with surrounding whitespace stripped so callers
|
|
2332
|
+
* can split on `.` to extract the leading entity name.
|
|
2333
|
+
*
|
|
2334
|
+
* Permissive on identifier shape — accepts kebab-free dot paths
|
|
2335
|
+
* (`icp.name`, `icp.profile.geographies`) and bare identifiers
|
|
2336
|
+
* (`icpRef`, `output_language`). Mustache section tokens
|
|
2337
|
+
* (`{{#...}}` / `{{^...}}` / `{{/...}}` / `{{!...}}`) are filtered
|
|
2338
|
+
* via the leading sigil check below.
|
|
2339
|
+
*/
|
|
2340
|
+
const MUSTACHE_PLACEHOLDER_REGEX = /\{\{\s*([^}]+?)\s*\}\}/g;
|
|
2341
|
+
|
|
2342
|
+
/**
|
|
2343
|
+
* Phase-4 (§10.3 of the plan) — declared/used coherence check on
|
|
2344
|
+
* `MarketMessageTemplate.promptTemplate` ↔ `requiredInputs[]`.
|
|
2345
|
+
*
|
|
2346
|
+
* The detector is symmetric: it surfaces both directions of drift
|
|
2347
|
+
* (declared but never substituted; used in the body but never
|
|
2348
|
+
* declared) under the same `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH`
|
|
2349
|
+
* kind. The message text disambiguates the direction so authors can
|
|
2350
|
+
* fix it from the report alone.
|
|
2351
|
+
*
|
|
2352
|
+
* The exempt token set ({{output_language}} today) is filtered before
|
|
2353
|
+
* the "used but not declared" pass — see
|
|
2354
|
+
* `PLACEHOLDER_ENTITY_EXEMPT_FROM_REQUIRED_INPUTS`. Unknown camelCase
|
|
2355
|
+
* roots (e.g. `{{persona.name}}` if persona ever becomes a placeholder
|
|
2356
|
+
* shape) are silently ignored — this detector covers ONLY the inputs
|
|
2357
|
+
* declared in `MarketMessageRequiredInput`. Adding a new required-input
|
|
2358
|
+
* shape requires extending both `PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT`
|
|
2359
|
+
* and `REQUIRED_INPUT_PLACEHOLDER_PATTERNS` together.
|
|
2360
|
+
*/
|
|
2361
|
+
function detectMessageTemplatePlaceholderMismatch(
|
|
2362
|
+
snapshot: MarketSnapshot,
|
|
2363
|
+
issues: MarketSnapshotIssue[],
|
|
2364
|
+
): void {
|
|
2365
|
+
for (const [tIdx, template] of snapshot.messageTemplates.entries()) {
|
|
2366
|
+
const declaredInputs = new Set<MarketMessageRequiredInput>(template.requiredInputs ?? []);
|
|
2367
|
+
|
|
2368
|
+
// Direction 1: declared but the body has no consuming placeholder.
|
|
2369
|
+
for (const declared of declaredInputs) {
|
|
2370
|
+
const pattern = REQUIRED_INPUT_PLACEHOLDER_PATTERNS[declared];
|
|
2371
|
+
if (pattern.test(template.promptTemplate)) continue;
|
|
2372
|
+
issues.push({
|
|
2373
|
+
kind: MarketSnapshotIssueKind.MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH,
|
|
2374
|
+
path: `messageTemplates[${tIdx}].requiredInputs`,
|
|
2375
|
+
message:
|
|
2376
|
+
`Message template "${template.ref}" declares requiredInput "${declared}" but no `
|
|
2377
|
+
+ `\`{{${declared.replace(/Ref$/, '')}.*}}\` / \`{{${declared}}}\` placeholder exists in promptTemplate. `
|
|
2378
|
+
+ `Add the placeholder or prune the requiredInput entry.`,
|
|
2379
|
+
severity: 'WARN',
|
|
2380
|
+
});
|
|
2381
|
+
}
|
|
2382
|
+
|
|
2383
|
+
// Direction 2: body references a known input shape that is not declared.
|
|
2384
|
+
const referencedInputs = new Set<MarketMessageRequiredInput>();
|
|
2385
|
+
MUSTACHE_PLACEHOLDER_REGEX.lastIndex = 0;
|
|
2386
|
+
let match: RegExpExecArray | null;
|
|
2387
|
+
while ((match = MUSTACHE_PLACEHOLDER_REGEX.exec(template.promptTemplate)) !== null) {
|
|
2388
|
+
const inner = match[1] ?? '';
|
|
2389
|
+
// Skip Mustache section / inverted / closing / comment tokens.
|
|
2390
|
+
const firstChar = inner[0];
|
|
2391
|
+
if (firstChar === '#' || firstChar === '^' || firstChar === '/' || firstChar === '!') continue;
|
|
2392
|
+
|
|
2393
|
+
const leadingEntity = inner.split('.')[0]?.trim() ?? '';
|
|
2394
|
+
if (leadingEntity.length === 0) continue;
|
|
2395
|
+
if (PLACEHOLDER_ENTITY_EXEMPT_FROM_REQUIRED_INPUTS.has(leadingEntity)) continue;
|
|
2396
|
+
|
|
2397
|
+
const consumedInput = lookupConsumedRequiredInput(inner);
|
|
2398
|
+
if (consumedInput === undefined) continue; // unknown entity root — out of scope for this detector
|
|
2399
|
+
referencedInputs.add(consumedInput);
|
|
2400
|
+
}
|
|
2401
|
+
|
|
2402
|
+
for (const referenced of referencedInputs) {
|
|
2403
|
+
if (declaredInputs.has(referenced)) continue;
|
|
2404
|
+
issues.push({
|
|
2405
|
+
kind: MarketSnapshotIssueKind.MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH,
|
|
2406
|
+
path: `messageTemplates[${tIdx}].promptTemplate`,
|
|
2407
|
+
message:
|
|
2408
|
+
`Message template "${template.ref}" references \`{{${referenced.replace(/Ref$/, '')}.*}}\` / `
|
|
2409
|
+
+ `\`{{${referenced}}}\` placeholders but does not declare "${referenced}" in requiredInputs[]. `
|
|
2410
|
+
+ `Add the requiredInput entry or remove the placeholder.`,
|
|
2411
|
+
severity: 'WARN',
|
|
2412
|
+
});
|
|
2413
|
+
}
|
|
2414
|
+
}
|
|
2415
|
+
}
|
|
2416
|
+
```
|
|
2417
|
+
|
|
2418
|
+
## Request payload reference
|
|
2419
|
+
|
|
2420
|
+
```ts
|
|
2421
|
+
// market-context-for-feature
|
|
2422
|
+
type MarketContextForFeatureRequest = {
|
|
2423
|
+
featureRef: string; // required, non-empty
|
|
2424
|
+
outputLanguage?: string; // optional BCP-47 tag (e.g. 'fr', 'de-DE')
|
|
2425
|
+
};
|
|
2426
|
+
|
|
2427
|
+
// market-context-for-icp
|
|
2428
|
+
type MarketContextForIcpRequest = {
|
|
2429
|
+
icpRef: string; // required, non-empty
|
|
2430
|
+
outputLanguage?: string; // optional BCP-47 tag
|
|
2431
|
+
};
|
|
2432
|
+
|
|
2433
|
+
// shared response
|
|
2434
|
+
type MarketContextResponse = {
|
|
2435
|
+
block: string; // English markdown — paste verbatim
|
|
2436
|
+
trace: MarketContextBlockTrace; // diagnostic — log in debug mode
|
|
2437
|
+
};
|
|
2438
|
+
```
|
|
2439
|
+
|
|
2440
|
+
The trace records which entities the renderer considered (benefits,
|
|
2441
|
+
ICPs, voice). Surface it in CLI debug logs so authoring drift
|
|
2442
|
+
("why did benefit X not appear?") is diagnosable from the consumer
|
|
2443
|
+
side without rebuilding the snapshot.
|