@wildo-ai/framework-knowledge 1.1.2 → 1.1.4
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/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +351 -18
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.schemas.d.ts +1 -2
- package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.schemas.js.map +1 -1
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +3 -4
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +4 -4
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +3 -4
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +4 -4
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +1 -2
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +1 -2
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +2 -3
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +3 -3
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +1 -2
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +1 -2
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +0 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +0 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +0 -2
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +2 -2
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +0 -2
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +9 -4
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +0 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/manifest.json +8 -9
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +13 -70
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +11 -19
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +5 -88
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +15 -8
- package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +4 -5
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +15 -8
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +4 -0
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +8 -7
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +22 -49
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +8 -17
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -780
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +11 -11
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +20 -141
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +15 -10
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +3 -2
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +16 -11
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +14 -6
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +4 -2
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +16 -7
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +4 -21
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +65 -16
- package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-analysis/method.md +165 -51
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +43 -23
- package/dist/knowledge/playbooks/top_down.phase-gate/method.md +4 -8
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +7 -9
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +7 -9
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +15 -7
- package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +3 -3
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +16 -11
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +4 -2
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +15 -7
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +2 -2
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +16 -11
- package/dist/knowledge/references/build-plan.task-graph.config.md +1 -45
- package/dist/knowledge/references/companion.technical-doc.service.md +2 -102
- package/dist/knowledge/references/example.config.app-shell.full.md +5 -0
- package/dist/knowledge/references/example.module.companion-exports.full.md +0 -1
- package/dist/knowledge/references/example.provider.backend-module-shape.md +0 -7
- package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +1 -0
- package/dist/knowledge/references/platform.config.saas.md +0 -51
- package/dist/knowledge/references/presets.models.surface-policy.md +10 -19
- package/dist/knowledge/references/saas.external-data.admin-endpoints.md +48 -0
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +11 -31
- package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +1 -0
- package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +0 -45
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +0 -198
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +0 -164
- package/dist/knowledge/references/saas.models.engine-capabilities.md +6 -26
- package/dist/knowledge/references/saas.models.http-api-binding.md +29 -3
- package/dist/knowledge/references/saas.models.provider-capabilities.md +3 -4
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +2 -4
- package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +0 -2
- package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +0 -14
- package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +31 -11
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +2 -32
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +6 -29
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +0 -56
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +0 -22
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +0 -26
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +0 -45
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +1 -7
- package/dist/knowledge/references/zod.decorators.field-spec-params.md +5 -31
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +1 -44
- package/dist/knowledge/references/zod.decorators.primitive-ui.md +0 -3
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +0 -1
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +0 -15
- package/dist/knowledge/registries/assurance-authority-bases.json +2 -3
- package/dist/knowledge/registries/framework-topics.json +11 -146
- package/dist/knowledge/registries/playbooks.json +18 -154
- package/dist/knowledge/registries/source-tags.json +630 -883
- package/dist/knowledge/skills/INDEX.md +3 -4
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +1 -2
- package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -16
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +9 -31
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +74 -252
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +8 -26
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +53 -97
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +21 -84
- package/dist/knowledge/skills/config-app-shell/SKILL.md +9 -31
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +12 -31
- package/dist/knowledge/skills/config-design-system/SKILL.md +1 -23
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +10 -19
- package/dist/knowledge/skills/config-navigation/SKILL.md +2 -75
- package/dist/knowledge/skills/config-saas/SKILL.md +2 -19
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +9 -30
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +0 -51
- package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +0 -7
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +1 -2
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +3 -4
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +0 -56
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +0 -56
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +0 -1
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +0 -56
- package/dist/knowledge/skills/resource-add-field/SKILL.md +3 -3
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +0 -213
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +1 -2
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +2 -4
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +0 -15
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +2 -224
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +0 -198
- package/dist/knowledge/skills/resource-external-data/SKILL.md +2 -0
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +29 -3
- package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +70 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +1 -22
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +8 -28
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +0 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +0 -17
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +0 -46
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +0 -15
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +0 -26
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +1 -7
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +0 -198
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +1 -44
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +0 -3
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +0 -1
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +0 -56
- package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +5 -31
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +0 -22
- package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +0 -45
- package/dist/knowledge/topic-index.json +220 -725
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +4 -4
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +0 -1
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +0 -51
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +0 -43
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +0 -185
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +0 -64
- package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +0 -41
- package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +0 -100
- package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +0 -117
- package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +0 -86
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +0 -61
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +0 -41
- package/dist/knowledge/playbooks/top_down.compliance-research/method.md +0 -76
- package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +0 -42
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +0 -56
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +0 -42
- package/dist/knowledge/playbooks/top_down.market-research/method.md +0 -68
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +0 -44
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +0 -239
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +0 -67
- package/dist/knowledge/references/placement-plan.config.md +0 -330
- package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +0 -34
- package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +0 -45
- package/dist/knowledge/references/saas.frontend.public-shell.identity-mode.md +0 -65
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +0 -58
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +0 -118
- package/dist/knowledge/references/saas.models.file-upload-grant.md +0 -179
- package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +0 -124
- package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +0 -99
- package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +0 -127
- package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +0 -42
- package/dist/knowledge/references/saas.specifications.application-authored-document-fact-specification.contract.md +0 -29
- package/dist/knowledge/references/zod.decorators.data-categories.md +0 -197
- package/dist/knowledge/rules/resource-schema-awareness.md +0 -77
- package/dist/knowledge/skills/config-app-shell/references/framework-public-shell-identity-api.md +0 -124
- package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md +0 -47
- package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +0 -98
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +0 -54
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +0 -232
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +0 -149
- package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +0 -114
- package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +0 -133
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +0 -111
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +0 -622
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-file-upload-grant-contract.md +0 -192
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +0 -245
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +0 -134
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +0 -65
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +0 -127
- /package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/structured-artifact-action.json +0 -0
|
@@ -5,6 +5,10 @@
|
|
|
5
5
|
"intent": "Bottom-up build dispatch — the SECOND build-execution playbook, the pivot from DECOMPOSING the build (the build-plan task graph) to DISPATCHING it: turning one ordered task into an actually-run, verified coding-agent run under the D4 dispatch contract. Reads the approved TYPED build-plan (`BuildPlanTaskGraph` — each task carries a closed target kind, ONE MetaWorkflow_FunctionalTopic, its skill refs, and DECLARED prerequisite task refs) and the current journey state, selects the NEXT READY task (`selectReadyBuildPlanTasks`: every declared prerequisite has landed — resolved by the host, never inferred from prose; SINGLE-FLIGHT — exactly ONE workspace-mutating run at a time), and dispatches exactly that typed task: (1) the runner builds the context pack (task brief + the task's skill pointers + the relevant journey/definition artifacts + introspected app reality + repo paths); (2) it runs ONE prompt turn against the coding agent over the Agent Client Protocol, in a session rooted at the app workspace (cwd = app root, so CLAUDE.md / .claude skills load naturally), answering the agent's permission requests within the execution profile's declared ceiling and refusing anything above it or outside the task's mutation scope; (3) it captures the change-set around the run (git baseline/post-run worktree snapshots → per-file attribution → a structured GitChangeSetCapture recorded on the task row); (4) it runs the VERIFY gate OUTSIDE the coding agent (a deterministic typecheck the runner maps onto the dispatch verification hook — pnpm exec tsc --noEmit — the trust-but-verify floor); (5) it records the result + applies the onFailure disposition (keep_and_flag: a failed/timed-out run keeps its captured change-set flagged for human triage, never a silent half-applied state). Then loop to the next ready task. This playbook PRODUCES the per-task dispatch contract + execution semantics; it authors no schemas and generates no code (the coding agent does that at dispatch time). It does NOT decompose the plan (that is the build-decompose playbook, upstream — it owns the task graph) and does NOT solve multi-agent SCALE — parallelism across several coding agents, the concurrency schedule, and interleaving the companion generation steps at scale are the downstream scale playbook. v1 scaffold: the single-flight dispatch contract; multi-agent parallelism, a run-completion serializer, and a revert_changeset failure path are later phases (revert is a MUTATING git op outside the read-only change-set carve-out, deliberately deferred).",
|
|
6
6
|
"functionalTopics": [],
|
|
7
7
|
"preconditions": [
|
|
8
|
+
{
|
|
9
|
+
"kind": "phase_is",
|
|
10
|
+
"phase": "bottom_up"
|
|
11
|
+
},
|
|
8
12
|
{
|
|
9
13
|
"kind": "artifact_exists",
|
|
10
14
|
"selector": {
|
|
@@ -18,21 +22,24 @@
|
|
|
18
22
|
}
|
|
19
23
|
],
|
|
20
24
|
"outputs": [],
|
|
21
|
-
"stepOutputs": [],
|
|
22
25
|
"method": {
|
|
23
|
-
"guidance": "# Build Dispatch — One Build-Plan Task → One Verified Coding-Agent Run (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut of the\n> *single-flight* dispatch contract — dispatch exactly ONE build-plan task at a\n> time, capture its change-set, verify it outside the coding agent, record it, and\n> apply the failure disposition. The context-pack shape, the verify gate, and the\n> failure-handling below are deliberately explicit so they can be tuned against real\n> runs. Multi-agent parallelism, a concurrency scheduler, a run-completion\n> serializer, and a `revert_changeset` failure path are a **later phase** — do not\n> build them here (see the boundary section).\n\n## Where you are in the journey\n\nThis is the **second build-execution playbook** — the pivot from **decomposing the\nbuild** (the build-plan: the ordered coding-agent task graph) to **dispatching it**\n(turning one ordered task into an actually-run, verified coding-agent run). It runs\nin the **bottom-up phase**, after the build plan exists (`artifact_exists\nbuild-plan`) and the foundation step has authored the app's config and skeleton.\nYou are not re-opening the decomposition\nhere — you are turning one *approved, ordered* task into a *dispatched, verified*\nchange to the application.\n\nUpstream, the **build-decompose** playbook produced the ordered task graph you\nconsume; downstream, the **scale** playbook generalises this single-flight contract\nto many concurrent coding agents and interleaves the companion generation steps.\n**You author neither of those concerns** — see the boundary section.\n\n## The typed task you dispatch\n\nThe build plan is a typed family (`BuildPlanTaskGraph`): dispatch selects ONE\nREADY task (all declared prerequisite task refs have landed) and hands the\ncoding host exactly that task's `objective`, `target`, `functionalTopic` and\n`skillRefs`. The host derives the physical allowed/prohibited paths and the\nfixed verification from the target kind; nothing in the task — and nothing in\nthis method prose — authors a path, a command, a prompt or a runtime control.\n\n## Import Origins\n\n- `@wildo-ai/saas-specifications`\n\n## Source Excerpts\n\n### Origin Package: `@wildo-ai/saas-specifications`\n\n```typescript\n *\n * Versioning for the build-plan task-graph payload format itself. `V1` —\n * initial shape (one ordered `tasks` collection with typed targets and\n * declared prerequisites). The shape grows additively across versions; the\n * `version` field is the explicit marker for consumers that branch on era.\n */\nexport enum BuildPlanTaskGraphVersion {\n V1 = 'v1',\n}\n\n/** Stable prefix every build-plan task ref carries; the trusted runtime stamps it, a provider supplies only the slug. */\nexport const BUILD_PLAN_TASK_REF_PREFIX = 'build-task-';\n\n/**\n * WHAT a build task builds — a closed vocabulary, because the host derives\n * the physical mutation scope and verification policy from the target kind\n * and the model must never author those powers through free text.\n */\nexport enum BuildPlanTaskTargetKind {\n /** A whole application module (its shared-lib registration, backend module and frontend module skeletons). */\n MODULE = 'MODULE',\n /** One build stage of one resource: schema → config → ui-behavior → spec. */\n RESOURCE_STAGE = 'RESOURCE_STAGE',\n /** One relationship between two resources. */\n RELATIONSHIP = 'RELATIONSHIP',\n /** A companion-owned deterministic generation step (labels, seeds, emails…) interleaved by the build loop, never a coding-agent run. */\n COMPANION_GENERATION_STEP = 'COMPANION_GENERATION_STEP',\n /**\n * Authoring one SHELL SURFACE's placement configuration from the accepted\n * placement plan — the settings rail, the sidebar, the user menu or the\n * command palette.\n *\n * Its own kind rather than a reuse of the neighbours, because none of them is\n * true of it: it is not a MODULE or a RESOURCE_STAGE (it is application-wide\n * and belongs to no resource), not a RELATIONSHIP, and emphatically not a\n * COMPANION_GENERATION_STEP — that kind is documented as \"never a coding-agent\n * run\" and writing `settings-hub.config.ts` is exactly a coding-agent run.\n * Borrowing one would hand the host the wrong mutation scope and the wrong\n * verification, which is what the closed vocabulary exists to prevent.\n */\n SHELL_PLACEMENT = 'SHELL_PLACEMENT',\n}\n\n/** The per-resource build stages, in their fixed order. */\nexport enum BuildPlanResourceStage {\n SCHEMA = 'SCHEMA',\n CONFIG = 'CONFIG',\n UI_BEHAVIOR = 'UI_BEHAVIOR',\n SPEC = 'SPEC',\n}\n\nconst SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);\n/**\n * A skill ref is the skill's FOLDER id in the app-knowledge catalog, which is\n * also its `SKILL.md` frontmatter `name` — one id, kebab-case. The host refuses\n * any skill name outside `[a-z0-9-]+`, so a ref that does not match this shape\n * can never resolve to an installed skill.\n */\nconst SkillRefSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);\nconst NonEmptyStringSchema = z.string().trim().min(1);\n\nexport const BuildPlanTaskTargetSchema = z.discriminatedUnion('kind', [\n z.strictObject({ kind: z.literal(BuildPlanTaskTargetKind.MODULE), moduleRef: SlugSchema }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.RESOURCE_STAGE),\n moduleRef: SlugSchema,\n resourceRef: SlugSchema,\n stage: z.enum(BuildPlanResourceStage),\n }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.RELATIONSHIP),\n moduleRef: SlugSchema,\n relationshipRef: SlugSchema,\n }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.COMPANION_GENERATION_STEP),\n /** The companion generation step this task runs (e.g. labels, seeds); resolved by the companion, never by a coding agent. */\n generationStepRef: SlugSchema,\n }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.SHELL_PLACEMENT),\n /**\n * Which shell surface this task authors — the placement family's OWN\n * `PlacementSurface`, deliberately not a build-plan copy of it.\n *\n * A copy was written first and was a defect, caught by probing the landing\n * renderer rather than by any test: `PlacementAddress` discriminates on\n * `surface` with `z.literal(...)` per option, so only the VALUES survive into\n * the schema, and the renderer resolves a discriminator by matching that value\n * SET against the exported enums. Two enums with identical values made the\n * match ambiguous, the renderer correctly refused to guess an owner, and the\n * address discriminator became unnameable — a landed placement plan would have\n * emitted `surface: \"SETTINGS_HUB\"` as a bare string instead of\n * `PlacementSurface.SETTINGS_HUB`. One concept, one named source.\n */\n surface: z.enum(PlacementSurface),\n }),\n]);\nexport type BuildPlanTaskTarget = z.infer<typeof BuildPlanTaskTargetSchema>;\n\n/**\n * One ordered build task. It names WHAT to build and WHY; it never carries\n * HOW (no paths, commands, prompts, cwd, model, profile). The host resolves\n * the physical allowed/prohibited paths and the fixed verification from the\n * target kind, and the installed skills from `skillRefs` against the app\n * knowledge catalog.\n *\n * Dependency readiness is DECLARED as prerequisite task refs and RESOLVED by\n * the host (a prerequisite is satisfied when its task has landed), never a\n * solved DAG the model must get right.\n */\nexport const BuildPlanTaskSchema = z.strictObject({\n /** `build-task-<slug>`, stamped by the trusted runtime. */\n taskRef: z.string().regex(new RegExp(`^${BUILD_PLAN_TASK_REF_PREFIX}[a-z0-9]+(?:-[a-z0-9]+)*$`)),\n /** One sentence of intent: what this task delivers. */\n objective: NonEmptyStringSchema,\n target: BuildPlanTaskTargetSchema,\n /**\n * Exactly ONE functional topic this task belongs to.\n *\n * **It does NOT drive ordering** — this said \"drives cross-app ordering\" until 2026-08-30 and\n * nothing ever ordered by it. Sequencing is `prerequisiteTaskRefs`, resolved by the host, and it\n * is the only thing that decides what may run next.\n *\n * What it DOES: the dispatch host stamps it into the coding-agent's task payload beside\n * `skillRefs`, so the agent is told which phase of building the application this task belongs to.\n * That is context an LLM reads, not a value the runtime branches on — the distinction matters,\n * because a reader who believes it orders will look here for a scheduling bug that lives in the\n * prerequisite graph. See issue #124.\n */\n functionalTopic: z.enum(MetaWorkflow_FunctionalTopic),\n /** Installed app-knowledge skill folders that carry the technical HOW; resolved via the skills router at dispatch. */\n skillRefs: z.array(SkillRefSchema).min(1),\n /** Task refs that must have landed first; resolved by the host, not solved by the model. */\n prerequisiteTaskRefs: z.array(z.string()).default([]),\n /** Requirement / roadmap refs this task serves (traceability only; never scope authority). */\n servesRefs: z.array(NonEmptyStringSchema).default([]),\n});\nexport type BuildPlanTask = z.infer<typeof BuildPlanTaskSchema>;\n\n/**\n * THE build-plan payload — a **single aggregate per product**: the ORDERED\n * task graph that turns the accepted domain plan into buildable units.\n *\n * **Artifact-family id: `build-plan`.** This schema is the shape of the\n * journey artifact selected by `MetaWorkflow_ArtifactSelector.family ===\n * 'build-plan'` (the `family` vocabulary stays an open string owned by the\n * selector surface; this note is the single place tying the SHAPE to the\n * NAME). Produced by the build-decompose playbook, consumed one task at a\n * time by build-dispatch (single-flight coding dispatch) and by the scale\n * playbook.\n *\n * Invariants enforced here: unique task refs; every prerequisite names a task\n * in this graph; no self-prerequisite. Cycle detection and ordering\n * soundness are the deterministic validator's job (`validateBuildPlanTaskGraph`).\n */\nexport const BuildPlanTaskGraphSchema = z.object({\n version: z.enum(BuildPlanTaskGraphVersion).default(BuildPlanTaskGraphVersion.V1),\n /**\n * At least one task, at the SCHEMA — not merely as a validator warning. The first live playbook-loop\n * run (2026-08-24) proved why: build-decompose answered `tasks: []`, which was schema-valid, passed\n * `_core` validation as a mere warning, and LANDED — overwriting a completed 3-task plan with a\n * vacuous artifact. Decomposing to zero tasks is a refusal (\"nothing to decompose\"), never an\n * artifact: an empty plan carries no information a reader could act on, and the file it replaces\n * does. Same vacuity class already closed on the requirements family (`functional: min(1)`).\n */\n tasks: z.array(BuildPlanTaskSchema).min(1),\n}).superRefine((graph, context) => {\n const refs = new Set<string>();\n graph.tasks.forEach((task, index) => {\n if (refs.has(task.taskRef)) {\n context.addIssue({ code: 'custom', message: `duplicate build task ref \"${task.taskRef}\"`, path: ['tasks', index, 'taskRef'] });\n }\n refs.add(task.taskRef);\n });\n graph.tasks.forEach((task, index) => {\n task.prerequisiteTaskRefs.forEach((prerequisite, prerequisiteIndex) => {\n if (prerequisite === task.taskRef) {\n context.addIssue({ code: 'custom', message: `build task \"${task.taskRef}\" cannot be its own prerequisite`, path: ['tasks', index, 'prerequisiteTaskRefs', prerequisiteIndex] });\n } else if (!refs.has(prerequisite)) {\n context.addIssue({ code: 'custom', message: `build task \"${task.taskRef}\" names an unknown prerequisite \"${prerequisite}\"`, path: ['tasks', index, 'prerequisiteTaskRefs', prerequisiteIndex] });\n }\n });\n });\n});\nexport type BuildPlanTaskGraph = z.infer<typeof BuildPlanTaskGraphSchema>;\n```\n\n## What this playbook does\n\nYou are the **dispatch orchestrator**. This playbook reads the approved build plan\nand the current journey state and answers, for *one* task at a time: *\"dispatch this\ntask safely, verify it, and record what happened.\"* You do **not** produce a new\njourney artifact — the dispatch's observable result (the change-set + the task\nstatus) is materialized by the runner on the task row, not authored here (see \"What\nyou emit\"). You do **not** decompose the plan, author any schema, or write any code\n— the coding agent writes the code at dispatch time; the plan is the\nbuild-decompose playbook's; scale is the scale playbook's.\n\n## The dispatch contract — the runner owns the mechanism, you sequence it\n\nMost of the D4 dispatch contract is **runner mechanism**, not prose you re-implement:\nthe runner composes the context pack, opens a coding session with the agent over the\nAgent Client Protocol and sends one prompt turn, answers the agent's permission\nrequests within the declared ceiling, captures the change-set, runs the verify hook,\nholds the single-flight lock, and enforces the budget floor. Your method here is the **declarative recipe** the runner interprets —\n*which* task to dispatch next, *when* it is authorized, and *how* its outcome is\njudged. Do not hand-compose a dispatch prompt or drive git yourself; let the runner\nown composition and change-set capture.\n\n## Read state first — no artifact to write\n\nThis playbook is **idempotent** and, on a re-run, *advances the loop by one task*.\nBefore dispatching anything:\n\n1. Read the current journey state and scope through the `journey-status` skill (it\n owns the read; do not re-derive it here). Confirm the **build plan** is present\n and approved, and confirm the **foundation** ran. For each build-plan task,\n determine its dispatch state from its task row — **not yet dispatched**,\n **dispatched-and-succeeded** (a captured change-set + a passed verify), or\n **dispatched-and-failed** (a captured change-set but a failed/timed-out run or a\n failed verify). This tri-state matters: under `keep_and_flag` a **failed** task\n *also* has a captured change-set, so \"has a change-set\" alone does NOT mean the\n task is done — read the task's terminal status + verify outcome, not just the\n presence of a change-set.\n2. Read the approved **build plan** (`build-plan` — the ordered task graph). It is your\n work list.\n\n Evidence that the foundation ran is `./wildo.saas.config.ts` itself, committed: the\n app either has a config and a skeleton or it does not, and git answers that without a\n journey artifact standing in for it. (A `foundation-manifest` family was that stand-in\n until 2026-08-25; it was retired with the app-creation verification/digest aspect, and\n this playbook no longer gates on it.) The honest limitation inherited from the\n foundation step still applies: at scaffold depth the on-disk skeleton *materialization*\n depends on greenfield bring-up tooling (deferred). The dispatch contract is real and\n runs against an **existing** app skeleton — the dogfood app already has one.\n\n// Operator status: `wildo context journey` (phase + board + runs in flight). Which tasks already\n// landed is read from GIT by the runner itself — a task is landed when every file it produces is\n// committed clean.\n\nYou **read** `build-plan`; you **write** no journey artifact\n— the runner records the change-set + task status on the dispatched task's row.\n\n## Precondition — the application must establish the agent's role, or dispatch stalls\n\nCheck this before the first dispatch of an application's life. It costs one look and it is the\ndifference between a working lane and one that burns model time producing nothing.\n\n**The application needs a root `CLAUDE.md` stating that a task dispatched by its dev companion is\nlegitimate work.** Without it the agent is right to refuse, and refusing is what it does.\n\nThe reason is structural rather than a matter of tone. A dispatched task reaches the agent as an\nordinary prompt — a user turn carrying an objective, a mutation scope and skill refs. Nothing in\nthat turn proves where it came from. So the agent is being handed conversational content that\ntells it to write files into a repository, which is indistinguishable from the thing every\ncareful agent is supposed to decline, and the more trustworthy the agent the more reliably it\ndeclines. Measured on a real application with no such file: two dispatched runs stalled, one\nanswering *\"content that arrives as conversational input doesn't get to reassign what I am\"*.\n\nThe failure does not look like a missing file. It looks like an agent that deliberates well,\nidentifies exactly which files it would author, explains its reasoning, asks a human to confirm,\nand ends its turn — `end_turn`, no error, no denial, an empty change set, and a bill for the\ntokens. Read as \"the agent chose not to work\", which invites prompt-tuning that cannot fix it.\n\n`wildo init` scaffolds this file. An application created before that, or one whose `CLAUDE.md`\ncovers only its own conventions, needs the section added. What it must establish:\n\n- the task is **selected by the host** from the accepted build plan, not composed by a caller;\n- it is **confined before it arrives** — the host answers every permission request against the\n declared mutation scope and refuses paths outside it, so the agent need not police itself;\n- it is **reversible** — every write is an uncommitted working edit, and a human commits.\n\nTwo smaller things belong in the same section, because both were observed costing a run:\n\n- **Say what `allowedPathPrefixes` are relative to.** The agent receives bare prefixes such as\n `shared-lib/src/modules/<module>/` with no root, and cannot verify its own confinement against\n them. One sentence naming the application root removes the ambiguity.\n- **Do not name a task so it reads as a fixture.** An agent that concludes it is looking at a\n smoke test will say so and stop. Name the task after the product change it makes.\n\n## Step 1 — Select the next dispatchable task (single-flight)\n\nWalk the build plan in its authored order and pick the **first** task that is not\nyet dispatched (or a previously-**failed** task cleared for retry — see Step 5) and\nwhose prose prerequisites have all **succeeded**. Dispatch **exactly one** such task\nper run. If **no** task is ready — every task has already succeeded, or the only\nundispatched tasks are blocked behind a still-unresolved failure — there is nothing\nto dispatch: report the loop as done (or blocked on the failed task) and stop. An\nempty build plan is the same: nothing to dispatch, stop.\n\n- **Single-flight — one workspace-mutating run at a time.** The dispatch lane holds\n ONE workspace-mutation lock for the whole background run; a run plan carries **at\n most one** coding-agent task, and a second concurrent dispatch is refused. This is\n a hard runner floor, not a suggestion — do not try to dispatch two tasks in one\n run to \"go faster\". Batching across many agents is the scale playbook's job.\n- **A prerequisite must have SUCCEEDED, not merely been attempted.** A task is ready\n only when every task it depends on is dispatched-and-succeeded (verify passed).\n A prerequisite that is dispatched-and-**failed** (its change-set is flagged for\n triage under `keep_and_flag`) does **not** satisfy the dependency — its dependents\n stay **blocked** until the failure is triaged and the prerequisite re-dispatched\n successfully. Do not build a config on a schema whose run failed. Never dispatch a\n task before the stage it depends on (a config before its schema, a spec before its\n ui-behavior — the build-decompose playbook ordered these).\n- **Companion-generation steps are not coding-agent dispatches.** A build-plan task\n marked as a companion-owned generation step (labels / i18n, email templates,\n seeds) runs through its deterministic companion endpoint, not the coding-agent\n dispatch lane. Route it there; do not dispatch a coding agent for it. Interleaving\n those steps *concurrently* with coding runs at scale is the scale playbook's job —\n here you simply run the ready one in its turn.\n\n## Step 2 — Authorize the mutating run (approve_before)\n\nA coding-agent dispatch **mutates the application workspace** — the highest-stakes\naction in the journey. This playbook's approval posture is `approve_before`: the run\nis authorized **before** it touches the tree. Settle the exact pending Authority\nRequest through the `journey-approve` interface-relay workflow; never start the\ndispatch on your own judgment.\n\n- Under the **GUIDED** autonomy preset the gate is verbatim; under **YOLO_LIGHT** it\n downgrades to a post-hoc result review; under **YOLO** it is auto (the\n non-bypassable **budget floor** — per-playbook and per-journey run/wall-time\n ceilings — is the guardrail no preset can lift).\n- **v1 gate granularity (be honest about the floor's reach).** The approval gate is\n currently **playbook-scoped for the journey**, not scoped to a single dispatch: the\n first authorization of this dispatch playbook admits the subsequent dispatches of it\n too (bounded by the run-count budget floor), rather than re-prompting per task. So\n `approve_before` here means \"the creator authorizes the **dispatch loop** before any\n task mutates the workspace\" — a real pre-mutation floor. A per-run, single-use gate\n is a deferred runner posture; until it lands, the budget ceiling + the per-task\n change-set capture + the verify gate are what bound the authorized loop.\n- The floor still hard-gates regardless of preset: once the dispatch playbook's run\n ceiling is reached, further dispatches are **refused** — that refusal is the\n correct outcome; report it, do not work around it.\n\n## Step 3 — Dispatch the task through the coding-agent contract\n\nTrigger the run through the `journey-run` skill. The runner then performs the D4\ndispatch contract for you (you do not hand-assemble any of it):\n\n1. **Context pack** — the runner composes the prompt: the task brief, the task's\n skill pointers (`Read .claude/skills/<skillRef>/SKILL.md first` — the per-task\n HOW-skills the build plan named on this task), the relevant journey / definition\n artifacts, an introspected app-reality block, and the repo paths.\n2. **Session and one prompt turn** — the runner starts the agent over the Agent\n Client Protocol and opens a session rooted at the app workspace (cwd = the\n application root, so `./CLAUDE.md`, the sub-`CLAUDE.md`s, and the `.claude/` rules\n and skills load naturally), then sends the task as a single prompt turn. It is a\n session rather than a one-shot process, which is what makes the next three things\n possible at all:\n - **Permissions are answered, not assumed.** The agent asks before each action it\n considers privileged; the runner answers within the execution profile's declared\n ceiling and refuses anything above it, or anything touching a path outside the\n task's mutation scope. Refusals are counted on the task row, so a run that was\n held back is distinguishable from a run that had nothing to do.\n - **The turn can be cancelled.** Cancellation asks the agent to stop and waits, so\n the run terminalises with its change-set intact instead of being killed — an\n operator who stops a run still needs to know what it had already written.\n - **Usage is reported.** Tokens and cost come back from the run itself rather than\n being unavailable, which is what lets the budget floor mean anything.\n3. **Change-set capture** — the runner captures a git worktree snapshot before and\n after the run and attributes each touched file (the run's own edit vs. an\n already-dirty parallel-session file vs. a file that appeared during the run),\n recording a structured change-set on the task row. On the dogfood tree,\n dirty-at-dispatch is the NORMAL state (parallel sessions), so the capture\n *attributes* rather than assuming the run had the tree to itself.\n\n// The trigger is the companion's run route (`POST /api/companion/playbooks/<ref>/run`, via the\n// workbench or HTTP) — there is no CLI trigger yet. The runner composes the typed context pack,\n// runs one ACP prompt turn, and captures the change-set.\n\n## Step 4 — Verify OUTSIDE the coding agent\n\nTrust, but verify. The verify gate runs **outside** the coding agent, after the run,\nso the agent cannot mark its own homework:\n\n- **`dispatch-typecheck` (deterministic — the auto-run trust floor).** The runner\n maps this `deterministic_validator` gate (`validatorRef: typecheck`) onto the\n dispatch verification hook and runs a typecheck (`pnpm exec tsc --noEmit`) over the\n application workspace after the run, **outside** the coding agent. This is a\n **real, wired** gate — it actually executes and its result is recorded on the task\n row. A run whose typecheck fails is a failed run (apply the failure disposition in\n Step 5). At scaffold depth the gate is a **workspace-wide** typecheck (one static\n gate for every dispatch of this playbook); narrowing it to the specific package a\n given task touched — a per-task `typecheck:<pkgDir>` or a `vitest:<path>` targeted\n at the task's tests — is a later refinement, since a static playbook gate cannot\n vary per task.\n- **`dispatch-outcome-sound` (declarative reviewer checklist).** The six-invariant\n reviewer checklist (task accomplished, change-set scoped to the task, verify ran +\n passed, attribution clean, failure disposition correct, boundary discipline)\n is the *trust-but-verify reviewer* pass. It is **declarative** — the creator's\n review checklist; the compiled build-dispatch Evaluation Treatment is what the\n runtime judges with, and the deterministic typecheck above is what runs\n automatically.\n\n## Step 5 — Record the result and apply the failure disposition\n\nThe runner records the change-set + the task's terminal status on the task row. On a\n**failed or timed-out** run, this playbook's `onFailure` is **`keep_and_flag`**: the\ncaptured change-set is **kept and flagged for human triage** — never silently\nreverted, and never left as an un-recorded half-applied state. The change-set capture\n*is* the flag: it attributes exactly which files the run touched, so a human can\nreview, keep, or unwind them.\n\n> **Why keep_and_flag, not revert_changeset (a v1 boundary).** Reverting a failed\n> run's edits is a *mutating* git operation, deliberately **outside** the read-only\n> change-set carve-out the dispatch lane observes (the runner *observes* git —\n> baseline/post-run snapshots — but stage/commit/revert stay a human/CLI concern).\n> So `keep_and_flag` is both the correct F-5 workspace-safety posture (no silent\n> half-applied state) and the behavior the runner actually enforces today. Wiring a\n> `revert_changeset` path is a deliberate later boundary decision, not a gap this\n> playbook papers over.\n\nOn a **succeeded** run (change-set captured + verify passed), the task is done and\nits dependents become eligible. On a **failed** run, the task is **not** done — it is\nflagged for human triage, and its dependents stay blocked (Step 1) until it is\ntriaged and cleared for re-dispatch. Triage is a human decision: keep + fix forward,\nunwind the flagged change-set by hand, or re-dispatch the task once its blocker is\nresolved. This playbook does not auto-retry a failed task — automated retry / backoff\nis a deferred build-loop-resilience concern, and human triage is the v1 disposition;\nhere the loop simply surfaces the failure and stops advancing that dependency chain.\n\nThen **loop**: on the next run of this playbook, `journey-status` reflects the\njust-dispatched task's outcome, and you select the next ready task (Step 1). Close a\nsignificant stretch of dispatches with a `journey-report` summary — what was\nproduced, which change-sets landed, what verify said, and any failed task left\nflagged for triage.\n\n## Refine, don't re-dispatch\n\n- **Never re-dispatch a SUCCEEDED task.** A task that is dispatched-and-succeeded\n (change-set captured + verify passed) is done — advance to the next ready task, do\n not re-run it because the plan was re-opened elsewhere. A dispatched-and-**failed**\n task is a different case: it is re-dispatchable once triaged (Step 5) — a captured\n change-set alone does not make a task \"finished\".\n- **Follow the plan's order.** If the build plan was refined upstream (a task added,\n an ordering corrected), respect the new order on the next selection — do not cache\n a stale work list across runs.\n- **A budget refusal is a real stop.** When the run ceiling is hit, stop dispatching\n and report what remains; do not do the coding work out-of-band to \"finish the\n build\" — that makes the journey's task history a lie.\n\n## Scaffold-depth boundary (owned by a sibling, or deferred to a later phase)\n\nKeep this playbook at **single-flight dispatch depth**. Explicitly **out of scope\nhere**:\n\n- **Re-decomposition.** You do NOT split modules/resources into tasks, re-order the\n graph, or add tasks — the **build-decompose** playbook owns the task graph. You\n read it and dispatch from it.\n- **Multi-agent scale + interleaving.** Running MANY coding agents concurrently, a\n concurrency scheduler, a run-completion serializer, and interleaving the companion\n generation steps *concurrently* with coding runs is the **scale** playbook. You\n dispatch **one** task at a time under the single-flight lock; you do NOT design the\n concurrency schedule.\n- **A `revert_changeset` failure path.** Undoing a failed run's edits is a mutating\n git op outside the read-only change-set carve-out — deferred. `keep_and_flag` (keep\n + flag the captured change-set for triage) is the v1 disposition.\n- **Auto-executed reviewer checklist.** The checklist ships **declarative** —\n the deterministic typecheck gate runs automatically and the compiled Evaluation\n Treatment is the judged protocol; nothing executes the checklist prose. Do not\n assume it auto-ran.\n- **Schema / field authoring + code generation.** You dispatch a task; the **coding\n agent** authors the fields, schemas, ui-behavior, and code at dispatch time. If you\n catch yourself writing application code or a resource schema here, stop — that is\n the dispatched agent's job, not the orchestrator's.\n\nIf you find yourself designing how MANY agents run concurrently rather than how ONE\ntask dispatches safely, stop — that is the scale playbook.\n\n## What you emit\n\n**No journey artifact.** This is a pure-orchestration playbook: the observable result\nof a dispatch — the **change-set** (files touched, attributed, summarized) and the\n**task status** — is materialized by the runner on the dispatched task's row, not\nauthored by this playbook. That is deliberately not duplicated into a separate\njourney artifact family: the task row already *is* the dispatch record, and a second\nhome for the same record would drift.\n\nThe creator authorizes each dispatch (approval posture `approve_before`) before it\nmutates the workspace, and reviews the recorded change-set + verify outcome after —\none verified task at a time, until the build plan is fully dispatched.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state,\n scope, and budget; confirm the build plan is approved and the foundation ran, and\n see which tasks already dispatched.\n- `.claude/skills/journey-approve/SKILL.md` — relay the exact pre-dispatch Authority Request\n gate decision that authorizes the workspace-mutating dispatch (never self-approve).\n- `.claude/skills/journey-run/SKILL.md` — trigger the dispatch and monitor it; the\n runner composes the context pack, runs one prompt turn against the coding agent in\n the app workspace, captures the change-set, and runs the verify hook.\n- `.claude/skills/journey-report/SKILL.md` — summarize a stretch of dispatches:\n what was produced, which change-sets landed, and what the verify gates said.\n\n## Reviewer checklist — `dispatch-outcome-sound`\n\nFormerly authored as an `llm_judge` quality gate; the generic rubric-only gate kind was retired at the flexible-intelligence hard cut (judgment now runs only through a compiled Evaluation Treatment). The checklist itself is creator-facing review guidance and is kept here, verbatim (minus the retired runner's closing sentence, and with repository-specific wording made application-neutral):\n\nJudge whether ONE dispatched build-plan task ran soundly under the D4 dispatch contract — the trust-but-verify reviewer pass OUTSIDE the coding agent. Assess six invariants and mark each PASS / CONCERN / GAP with a one-line evidence note. (1) TASK ACCOMPLISHED — the change-set the run produced actually implements the dispatched task's target + stage (e.g. a schema task added the persisted shape; a ui-behavior task added field displays); a run whose change-set does not advance the task's stated target is a GAP (the dispatch produced nothing useful), and an empty change-set on a task that should have authored files is a GAP. (2) CHANGE-SET SCOPED TO THE TASK — the files touched belong to the task's target (its module / resource / stage) and the app workspace; edits sprawling into unrelated modules, Wildo package source outside the application workspace, or files no build-plan task owns are a CONCERN (scope creep the reviewer must flag). On the dogfood tree, files attributed BASELINE_DIRTY_AMBIGUOUS (already dirty at dispatch baseline — a parallel session, not this run) are review-required and must NOT be counted against the run. (3) VERIFY RAN + PASSED — the deterministic verify gate (typecheck) ran OUTSIDE the coding agent after the run and passed; a run recorded as succeeded whose typecheck the reviewer cannot confirm passed is a CONCERN, and a run whose typecheck FAILED but was recorded succeeded is a GAP. (4) ATTRIBUTION CLEAN (the single-flight signal) — the run's edits are cleanly attributable to it in the captured change-set (files classed RUN_EXCLUSIVE or APPEARED_DURING_RUN), consistent with the single-flight lock having held for this dispatch. A change-set the capture could NOT cleanly attribute to the run — dominated by BASELINE_DIRTY_AMBIGUOUS overlap, or captured across a HEAD that moved mid-run — is a CONCERN the reviewer must resolve by hand before accepting the run, not a clean pass (single-flight is a hard runner floor, so this invariant reads the attribution the run actually recorded rather than re-proving the lock). (5) FAILURE DISPOSITION CORRECT — a failed/timed-out run's captured change-set is KEPT + FLAGGED for human triage (keep_and_flag), never silently reverted nor silently left as an un-recorded half-applied state; a failed run with no recorded change-set flag is a GAP (F-5 workspace-safety violation). (6) BOUNDARY DISCIPLINE — the dispatch stays at single-task depth: it dispatches ONE task, captures + verifies + records it, and applies onFailure. It does NOT re-decompose the plan (the build-decompose playbook owns the task graph), does NOT run MANY coding agents concurrently / design a concurrency scheduler / interleave the companion generation steps at scale (the scale playbook), and does NOT itself author schemas / fields / code (the coding agent does that at dispatch time). Evidence of re-decomposition, multi-agent scale orchestration, or the dispatcher authoring code itself is a CONCERN (scope creep out of the single-flight dispatch lane). (The checklist is declarative: nothing executes it; the deterministic gates and the creator's approval remain the floors.)\n",
|
|
26
|
+
"guidance": "# Build Dispatch — One Build-Plan Task → One Verified Coding-Agent Run (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut of the\n> *single-flight* dispatch contract — dispatch exactly ONE build-plan task at a\n> time, capture its change-set, verify it outside the coding agent, record it, and\n> apply the failure disposition. The context-pack shape, the verify gate, and the\n> failure-handling below are deliberately explicit so they can be tuned against real\n> runs. Multi-agent parallelism, a concurrency scheduler, a run-completion\n> serializer, and a `revert_changeset` failure path are a **later phase** — do not\n> build them here (see the boundary section).\n\n## Where you are in the journey\n\nThis is the **second build-execution playbook** — the pivot from **decomposing the\nbuild** (the build-plan: the ordered coding-agent task graph) to **dispatching it**\n(turning one ordered task into an actually-run, verified coding-agent run). It runs\nin the **bottom-up phase**, after the build plan exists (`artifact_exists\nbuild-plan`) and the foundation step has authored the app's config and skeleton.\nYou are not re-opening the decomposition\nhere — you are turning one *approved, ordered* task into a *dispatched, verified*\nchange to the application.\n\nUpstream, the **build-decompose** playbook produced the ordered task graph you\nconsume; downstream, the **scale** playbook generalises this single-flight contract\nto many concurrent coding agents and interleaves the companion generation steps.\n**You author neither of those concerns** — see the boundary section.\n\n## The typed task you dispatch\n\nThe build plan is a typed family (`BuildPlanTaskGraph`): dispatch selects ONE\nREADY task (all declared prerequisite task refs have landed) and hands the\ncoding host exactly that task's `objective`, `target`, `functionalTopic` and\n`skillRefs`. The host derives the physical allowed/prohibited paths and the\nfixed verification from the target kind; nothing in the task — and nothing in\nthis method prose — authors a path, a command, a prompt or a runtime control.\n\n## Import Origins\n\n- `@wildo-ai/saas-specifications`\n\n## Source Excerpts\n\n### Origin Package: `@wildo-ai/saas-specifications`\n\n```typescript\n *\n * Versioning for the build-plan task-graph payload format itself. `V1` —\n * initial shape (one ordered `tasks` collection with typed targets and\n * declared prerequisites). The shape grows additively across versions; the\n * `version` field is the explicit marker for consumers that branch on era.\n */\nexport enum BuildPlanTaskGraphVersion {\n V1 = 'v1',\n}\n\n/** Stable prefix every build-plan task ref carries; the trusted runtime stamps it, a provider supplies only the slug. */\nexport const BUILD_PLAN_TASK_REF_PREFIX = 'build-task-';\n\n/**\n * WHAT a build task builds — a closed vocabulary, because the host derives\n * the physical mutation scope and verification policy from the target kind\n * and the model must never author those powers through free text.\n */\nexport enum BuildPlanTaskTargetKind {\n /** A whole application module (its shared-lib registration, backend module and frontend module skeletons). */\n MODULE = 'MODULE',\n /** One build stage of one resource: schema → config → ui-behavior → spec. */\n RESOURCE_STAGE = 'RESOURCE_STAGE',\n /** One relationship between two resources. */\n RELATIONSHIP = 'RELATIONSHIP',\n /** A companion-owned deterministic generation step (labels, seeds, emails…) interleaved by the build loop, never a coding-agent run. */\n COMPANION_GENERATION_STEP = 'COMPANION_GENERATION_STEP',\n}\n\n/** The per-resource build stages, in their fixed order. */\nexport enum BuildPlanResourceStage {\n SCHEMA = 'SCHEMA',\n CONFIG = 'CONFIG',\n UI_BEHAVIOR = 'UI_BEHAVIOR',\n SPEC = 'SPEC',\n}\n\nconst SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);\n/**\n * A skill ref is the skill's FOLDER id in the app-knowledge catalog, which is\n * also its `SKILL.md` frontmatter `name` — one id, kebab-case. The host refuses\n * any skill name outside `[a-z0-9-]+`, so a ref that does not match this shape\n * can never resolve to an installed skill.\n */\nconst SkillRefSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);\nconst NonEmptyStringSchema = z.string().trim().min(1);\n\nexport const BuildPlanTaskTargetSchema = z.discriminatedUnion('kind', [\n z.strictObject({ kind: z.literal(BuildPlanTaskTargetKind.MODULE), moduleRef: SlugSchema }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.RESOURCE_STAGE),\n moduleRef: SlugSchema,\n resourceRef: SlugSchema,\n stage: z.enum(BuildPlanResourceStage),\n }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.RELATIONSHIP),\n moduleRef: SlugSchema,\n relationshipRef: SlugSchema,\n }),\n z.strictObject({\n kind: z.literal(BuildPlanTaskTargetKind.COMPANION_GENERATION_STEP),\n /** The companion generation step this task runs (e.g. labels, seeds); resolved by the companion, never by a coding agent. */\n generationStepRef: SlugSchema,\n }),\n]);\nexport type BuildPlanTaskTarget = z.infer<typeof BuildPlanTaskTargetSchema>;\n\n/**\n * One ordered build task. It names WHAT to build and WHY; it never carries\n * HOW (no paths, commands, prompts, cwd, model, profile). The host resolves\n * the physical allowed/prohibited paths and the fixed verification from the\n * target kind, and the installed skills from `skillRefs` against the app\n * knowledge catalog.\n *\n * Dependency readiness is DECLARED as prerequisite task refs and RESOLVED by\n * the host (a prerequisite is satisfied when its task has landed), never a\n * solved DAG the model must get right.\n */\nexport const BuildPlanTaskSchema = z.strictObject({\n /** `build-task-<slug>`, stamped by the trusted runtime. */\n taskRef: z.string().regex(new RegExp(`^${BUILD_PLAN_TASK_REF_PREFIX}[a-z0-9]+(?:-[a-z0-9]+)*$`)),\n /** One sentence of intent: what this task delivers. */\n objective: NonEmptyStringSchema,\n target: BuildPlanTaskTargetSchema,\n /** Exactly ONE functional topic this task belongs to (drives cross-app ordering). */\n functionalTopic: z.enum(MetaWorkflow_FunctionalTopic),\n /** Installed app-knowledge skill folders that carry the technical HOW; resolved via the skills router at dispatch. */\n skillRefs: z.array(SkillRefSchema).min(1),\n /** Task refs that must have landed first; resolved by the host, not solved by the model. */\n prerequisiteTaskRefs: z.array(z.string()).default([]),\n /** Requirement / roadmap refs this task serves (traceability only; never scope authority). */\n servesRefs: z.array(NonEmptyStringSchema).default([]),\n});\nexport type BuildPlanTask = z.infer<typeof BuildPlanTaskSchema>;\n\n/**\n * THE build-plan payload — a **single aggregate per product**: the ORDERED\n * task graph that turns the accepted domain plan into buildable units.\n *\n * **Artifact-family id: `build-plan`.** This schema is the shape of the\n * journey artifact selected by `MetaWorkflow_ArtifactSelector.family ===\n * 'build-plan'` (the `family` vocabulary stays an open string owned by the\n * selector surface; this note is the single place tying the SHAPE to the\n * NAME). Produced by the build-decompose playbook, consumed one task at a\n * time by build-dispatch (single-flight coding dispatch) and by the scale\n * playbook.\n *\n * Invariants enforced here: unique task refs; every prerequisite names a task\n * in this graph; no self-prerequisite. Cycle detection and ordering\n * soundness are the deterministic validator's job (`validateBuildPlanTaskGraph`).\n */\nexport const BuildPlanTaskGraphSchema = z.object({\n version: z.enum(BuildPlanTaskGraphVersion).default(BuildPlanTaskGraphVersion.V1),\n /**\n * At least one task, at the SCHEMA — not merely as a validator warning. The first live playbook-loop\n * run (2026-08-24) proved why: build-decompose answered `tasks: []`, which was schema-valid, passed\n * `_core` validation as a mere warning, and LANDED — overwriting a completed 3-task plan with a\n * vacuous artifact. Decomposing to zero tasks is a refusal (\"nothing to decompose\"), never an\n * artifact: an empty plan carries no information a reader could act on, and the file it replaces\n * does. Same vacuity class already closed on the requirements family (`functional: min(1)`).\n */\n tasks: z.array(BuildPlanTaskSchema).min(1),\n}).superRefine((graph, context) => {\n const refs = new Set<string>();\n graph.tasks.forEach((task, index) => {\n if (refs.has(task.taskRef)) {\n context.addIssue({ code: 'custom', message: `duplicate build task ref \"${task.taskRef}\"`, path: ['tasks', index, 'taskRef'] });\n }\n refs.add(task.taskRef);\n });\n graph.tasks.forEach((task, index) => {\n task.prerequisiteTaskRefs.forEach((prerequisite, prerequisiteIndex) => {\n if (prerequisite === task.taskRef) {\n context.addIssue({ code: 'custom', message: `build task \"${task.taskRef}\" cannot be its own prerequisite`, path: ['tasks', index, 'prerequisiteTaskRefs', prerequisiteIndex] });\n } else if (!refs.has(prerequisite)) {\n context.addIssue({ code: 'custom', message: `build task \"${task.taskRef}\" names an unknown prerequisite \"${prerequisite}\"`, path: ['tasks', index, 'prerequisiteTaskRefs', prerequisiteIndex] });\n }\n });\n });\n});\nexport type BuildPlanTaskGraph = z.infer<typeof BuildPlanTaskGraphSchema>;\n```\n\n## What this playbook does\n\nYou are the **dispatch orchestrator**. This playbook reads the approved build plan\nand the current journey state and answers, for *one* task at a time: *\"dispatch this\ntask safely, verify it, and record what happened.\"* You do **not** produce a new\njourney artifact — the dispatch's observable result (the change-set + the task\nstatus) is materialized by the runner on the task row, not authored here (see \"What\nyou emit\"). You do **not** decompose the plan, author any schema, or write any code\n— the coding agent writes the code at dispatch time; the plan is the\nbuild-decompose playbook's; scale is the scale playbook's.\n\n## The dispatch contract — the runner owns the mechanism, you sequence it\n\nMost of the D4 dispatch contract is **runner mechanism**, not prose you re-implement:\nthe runner composes the context pack, opens a coding session with the agent over the\nAgent Client Protocol and sends one prompt turn, answers the agent's permission\nrequests within the declared ceiling, captures the change-set, runs the verify hook,\nholds the single-flight lock, and enforces the budget floor. Your method here is the **declarative recipe** the runner interprets —\n*which* task to dispatch next, *when* it is authorized, and *how* its outcome is\njudged. Do not hand-compose a dispatch prompt or drive git yourself; let the runner\nown composition and change-set capture.\n\n## Read state first — no artifact to write\n\nThis playbook is **idempotent** and, on a re-run, *advances the loop by one task*.\nBefore dispatching anything:\n\n1. Read the current journey state and scope through the `journey-status` skill (it\n owns the read; do not re-derive it here). Confirm the **build plan** is present\n and approved, and confirm the **foundation** ran. For each build-plan task,\n determine its dispatch state from its task row — **not yet dispatched**,\n **dispatched-and-succeeded** (a captured change-set + a passed verify), or\n **dispatched-and-failed** (a captured change-set but a failed/timed-out run or a\n failed verify). This tri-state matters: under `keep_and_flag` a **failed** task\n *also* has a captured change-set, so \"has a change-set\" alone does NOT mean the\n task is done — read the task's terminal status + verify outcome, not just the\n presence of a change-set.\n2. Read the approved **build plan** (`build-plan` — the ordered task graph). It is your\n work list.\n\n Evidence that the foundation ran is `./wildo.saas.config.ts` itself, committed: the\n app either has a config and a skeleton or it does not, and git answers that without a\n journey artifact standing in for it. (A `foundation-manifest` family was that stand-in\n until 2026-08-25; it was retired with the app-creation verification/digest aspect, and\n this playbook no longer gates on it.) The honest limitation inherited from the\n foundation step still applies: at scaffold depth the on-disk skeleton *materialization*\n depends on greenfield bring-up tooling (deferred). The dispatch contract is real and\n runs against an **existing** app skeleton — the dogfood app already has one.\n\n// TODO CLI COMMAND: wildo journey status\n// (read current journey scope + the approved build plan + which tasks already dispatched)\n\nYou **read** `build-plan`; you **write** no journey artifact\n— the runner records the change-set + task status on the dispatched task's row.\n\n## Step 1 — Select the next dispatchable task (single-flight)\n\nWalk the build plan in its authored order and pick the **first** task that is not\nyet dispatched (or a previously-**failed** task cleared for retry — see Step 5) and\nwhose prose prerequisites have all **succeeded**. Dispatch **exactly one** such task\nper run. If **no** task is ready — every task has already succeeded, or the only\nundispatched tasks are blocked behind a still-unresolved failure — there is nothing\nto dispatch: report the loop as done (or blocked on the failed task) and stop. An\nempty build plan is the same: nothing to dispatch, stop.\n\n- **Single-flight — one workspace-mutating run at a time.** The dispatch lane holds\n ONE workspace-mutation lock for the whole background run; a run plan carries **at\n most one** coding-agent task, and a second concurrent dispatch is refused. This is\n a hard runner floor, not a suggestion — do not try to dispatch two tasks in one\n run to \"go faster\". Batching across many agents is the scale playbook's job.\n- **A prerequisite must have SUCCEEDED, not merely been attempted.** A task is ready\n only when every task it depends on is dispatched-and-succeeded (verify passed).\n A prerequisite that is dispatched-and-**failed** (its change-set is flagged for\n triage under `keep_and_flag`) does **not** satisfy the dependency — its dependents\n stay **blocked** until the failure is triaged and the prerequisite re-dispatched\n successfully. Do not build a config on a schema whose run failed. Never dispatch a\n task before the stage it depends on (a config before its schema, a spec before its\n ui-behavior — the build-decompose playbook ordered these).\n- **Companion-generation steps are not coding-agent dispatches.** A build-plan task\n marked as a companion-owned generation step (labels / i18n, email templates,\n seeds) runs through its deterministic companion endpoint, not the coding-agent\n dispatch lane. Route it there; do not dispatch a coding agent for it. Interleaving\n those steps *concurrently* with coding runs at scale is the scale playbook's job —\n here you simply run the ready one in its turn.\n\n## Step 2 — Authorize the mutating run (approve_before)\n\nA coding-agent dispatch **mutates the application workspace** — the highest-stakes\naction in the journey. This playbook's approval posture is `approve_before`: the run\nis authorized **before** it touches the tree. Settle the exact pending Authority\nRequest through the `journey-approve` interface-relay workflow; never start the\ndispatch on your own judgment.\n\n- Under the **GUIDED** autonomy preset the gate is verbatim; under **YOLO_LIGHT** it\n downgrades to a post-hoc result review; under **YOLO** it is auto (the\n non-bypassable **budget floor** — per-playbook and per-journey run/wall-time\n ceilings — is the guardrail no preset can lift).\n- **v1 gate granularity (be honest about the floor's reach).** The approval gate is\n currently **playbook-scoped for the journey**, not scoped to a single dispatch: the\n first authorization of this dispatch playbook admits the subsequent dispatches of it\n too (bounded by the run-count budget floor), rather than re-prompting per task. So\n `approve_before` here means \"the creator authorizes the **dispatch loop** before any\n task mutates the workspace\" — a real pre-mutation floor. A per-run, single-use gate\n is a deferred runner posture; until it lands, the budget ceiling + the per-task\n change-set capture + the verify gate are what bound the authorized loop.\n- The floor still hard-gates regardless of preset: once the dispatch playbook's run\n ceiling is reached, further dispatches are **refused** — that refusal is the\n correct outcome; report it, do not work around it.\n\n## Step 3 — Dispatch the task through the coding-agent contract\n\nTrigger the run through the `journey-run` skill. The runner then performs the D4\ndispatch contract for you (you do not hand-assemble any of it):\n\n1. **Context pack** — the runner composes the prompt: the task brief, the task's\n skill pointers (`Read .claude/skills/<skillRef>/SKILL.md first` — the per-task\n HOW-skills the build plan named on this task), the relevant journey / definition\n artifacts, an introspected app-reality block, and the repo paths.\n2. **Session and one prompt turn** — the runner starts the agent over the Agent\n Client Protocol and opens a session rooted at the app workspace (cwd = the\n application root, so `./CLAUDE.md`, the sub-`CLAUDE.md`s, and the `.claude/` rules\n and skills load naturally), then sends the task as a single prompt turn. It is a\n session rather than a one-shot process, which is what makes the next three things\n possible at all:\n - **Permissions are answered, not assumed.** The agent asks before each action it\n considers privileged; the runner answers within the execution profile's declared\n ceiling and refuses anything above it, or anything touching a path outside the\n task's mutation scope. Refusals are counted on the task row, so a run that was\n held back is distinguishable from a run that had nothing to do.\n - **The turn can be cancelled.** Cancellation asks the agent to stop and waits, so\n the run terminalises with its change-set intact instead of being killed — an\n operator who stops a run still needs to know what it had already written.\n - **Usage is reported.** Tokens and cost come back from the run itself rather than\n being unavailable, which is what lets the budget floor mean anything.\n3. **Change-set capture** — the runner captures a git worktree snapshot before and\n after the run and attributes each touched file (the run's own edit vs. an\n already-dirty parallel-session file vs. a file that appeared during the run),\n recording a structured change-set on the task row. On the dogfood tree,\n dirty-at-dispatch is the NORMAL state (parallel sessions), so the capture\n *attributes* rather than assuming the run had the tree to itself.\n\n// TODO CLI COMMAND: wildo journey run <playbookRef>\n// (trigger the dispatch; the runner composes the context pack + runs one ACP prompt turn + captures the change-set)\n\n## Step 4 — Verify OUTSIDE the coding agent\n\nTrust, but verify. The verify gate runs **outside** the coding agent, after the run,\nso the agent cannot mark its own homework:\n\n- **`dispatch-typecheck` (deterministic — the auto-run trust floor).** The runner\n maps this `deterministic_validator` gate (`validatorRef: typecheck`) onto the\n dispatch verification hook and runs a typecheck (`pnpm exec tsc --noEmit`) over the\n application workspace after the run, **outside** the coding agent. This is a\n **real, wired** gate — it actually executes and its result is recorded on the task\n row. A run whose typecheck fails is a failed run (apply the failure disposition in\n Step 5). At scaffold depth the gate is a **workspace-wide** typecheck (one static\n gate for every dispatch of this playbook); narrowing it to the specific package a\n given task touched — a per-task `typecheck:<pkgDir>` or a `vitest:<path>` targeted\n at the task's tests — is a later refinement, since a static playbook gate cannot\n vary per task.\n- **`dispatch-outcome-sound` (declarative reviewer checklist).** The six-invariant\n reviewer checklist (task accomplished, change-set scoped to the task, verify ran +\n passed, attribution clean, failure disposition correct, boundary discipline)\n is the *trust-but-verify reviewer* pass. It is **declarative** — the creator's\n review checklist; the compiled build-dispatch Evaluation Treatment is what the\n runtime judges with, and the deterministic typecheck above is what runs\n automatically.\n\n## Step 5 — Record the result and apply the failure disposition\n\nThe runner records the change-set + the task's terminal status on the task row. On a\n**failed or timed-out** run, this playbook's `onFailure` is **`keep_and_flag`**: the\ncaptured change-set is **kept and flagged for human triage** — never silently\nreverted, and never left as an un-recorded half-applied state. The change-set capture\n*is* the flag: it attributes exactly which files the run touched, so a human can\nreview, keep, or unwind them.\n\n> **Why keep_and_flag, not revert_changeset (a v1 boundary).** Reverting a failed\n> run's edits is a *mutating* git operation, deliberately **outside** the read-only\n> change-set carve-out the dispatch lane observes (the runner *observes* git —\n> baseline/post-run snapshots — but stage/commit/revert stay a human/CLI concern).\n> So `keep_and_flag` is both the correct F-5 workspace-safety posture (no silent\n> half-applied state) and the behavior the runner actually enforces today. Wiring a\n> `revert_changeset` path is a deliberate later boundary decision, not a gap this\n> playbook papers over.\n\nOn a **succeeded** run (change-set captured + verify passed), the task is done and\nits dependents become eligible. On a **failed** run, the task is **not** done — it is\nflagged for human triage, and its dependents stay blocked (Step 1) until it is\ntriaged and cleared for re-dispatch. Triage is a human decision: keep + fix forward,\nunwind the flagged change-set by hand, or re-dispatch the task once its blocker is\nresolved. This playbook does not auto-retry a failed task — automated retry / backoff\nis a deferred build-loop-resilience concern, and human triage is the v1 disposition;\nhere the loop simply surfaces the failure and stops advancing that dependency chain.\n\nThen **loop**: on the next run of this playbook, `journey-status` reflects the\njust-dispatched task's outcome, and you select the next ready task (Step 1). Close a\nsignificant stretch of dispatches with a `journey-report` summary — what was\nproduced, which change-sets landed, what verify said, and any failed task left\nflagged for triage.\n\n## Refine, don't re-dispatch\n\n- **Never re-dispatch a SUCCEEDED task.** A task that is dispatched-and-succeeded\n (change-set captured + verify passed) is done — advance to the next ready task, do\n not re-run it because the plan was re-opened elsewhere. A dispatched-and-**failed**\n task is a different case: it is re-dispatchable once triaged (Step 5) — a captured\n change-set alone does not make a task \"finished\".\n- **Follow the plan's order.** If the build plan was refined upstream (a task added,\n an ordering corrected), respect the new order on the next selection — do not cache\n a stale work list across runs.\n- **A budget refusal is a real stop.** When the run ceiling is hit, stop dispatching\n and report what remains; do not do the coding work out-of-band to \"finish the\n build\" — that makes the journey's task history a lie.\n\n## Scaffold-depth boundary (owned by a sibling, or deferred to a later phase)\n\nKeep this playbook at **single-flight dispatch depth**. Explicitly **out of scope\nhere**:\n\n- **Re-decomposition.** You do NOT split modules/resources into tasks, re-order the\n graph, or add tasks — the **build-decompose** playbook owns the task graph. You\n read it and dispatch from it.\n- **Multi-agent scale + interleaving.** Running MANY coding agents concurrently, a\n concurrency scheduler, a run-completion serializer, and interleaving the companion\n generation steps *concurrently* with coding runs is the **scale** playbook. You\n dispatch **one** task at a time under the single-flight lock; you do NOT design the\n concurrency schedule.\n- **A `revert_changeset` failure path.** Undoing a failed run's edits is a mutating\n git op outside the read-only change-set carve-out — deferred. `keep_and_flag` (keep\n + flag the captured change-set for triage) is the v1 disposition.\n- **Auto-executed reviewer checklist.** The checklist ships **declarative** —\n the deterministic typecheck gate runs automatically and the compiled Evaluation\n Treatment is the judged protocol; nothing executes the checklist prose. Do not\n assume it auto-ran.\n- **Schema / field authoring + code generation.** You dispatch a task; the **coding\n agent** authors the fields, schemas, ui-behavior, and code at dispatch time. If you\n catch yourself writing application code or a resource schema here, stop — that is\n the dispatched agent's job, not the orchestrator's.\n\nIf you find yourself designing how MANY agents run concurrently rather than how ONE\ntask dispatches safely, stop — that is the scale playbook.\n\n## What you emit\n\n**No journey artifact.** This is a pure-orchestration playbook: the observable result\nof a dispatch — the **change-set** (files touched, attributed, summarized) and the\n**task status** — is materialized by the runner on the dispatched task's row, not\nauthored by this playbook. That is deliberately not duplicated into a separate\njourney artifact family: the task row already *is* the dispatch record, and a second\nhome for the same record would drift.\n\nThe creator authorizes each dispatch (approval posture `approve_before`) before it\nmutates the workspace, and reviews the recorded change-set + verify outcome after —\none verified task at a time, until the build plan is fully dispatched.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state,\n scope, and budget; confirm the build plan is approved and the foundation ran, and\n see which tasks already dispatched.\n- `.claude/skills/journey-approve/SKILL.md` — relay the exact pre-dispatch Authority Request\n gate decision that authorizes the workspace-mutating dispatch (never self-approve).\n- `.claude/skills/journey-run/SKILL.md` — trigger the dispatch and monitor it; the\n runner composes the context pack, runs one prompt turn against the coding agent in\n the app workspace, captures the change-set, and runs the verify hook.\n- `.claude/skills/journey-report/SKILL.md` — summarize a stretch of dispatches:\n what was produced, which change-sets landed, and what the verify gates said.\n\n## Reviewer checklist — `dispatch-outcome-sound`\n\nFormerly authored as an `llm_judge` quality gate; the generic rubric-only gate kind was retired at the flexible-intelligence hard cut (judgment now runs only through a compiled Evaluation Treatment). The checklist itself is creator-facing review guidance and is kept here, verbatim (minus the retired runner's closing sentence, and with repository-specific wording made application-neutral):\n\nJudge whether ONE dispatched build-plan task ran soundly under the D4 dispatch contract — the trust-but-verify reviewer pass OUTSIDE the coding agent. Assess six invariants and mark each PASS / CONCERN / GAP with a one-line evidence note. (1) TASK ACCOMPLISHED — the change-set the run produced actually implements the dispatched task's target + stage (e.g. a schema task added the persisted shape; a ui-behavior task added field displays); a run whose change-set does not advance the task's stated target is a GAP (the dispatch produced nothing useful), and an empty change-set on a task that should have authored files is a GAP. (2) CHANGE-SET SCOPED TO THE TASK — the files touched belong to the task's target (its module / resource / stage) and the app workspace; edits sprawling into unrelated modules, Wildo package source outside the application workspace, or files no build-plan task owns are a CONCERN (scope creep the reviewer must flag). On the dogfood tree, files attributed BASELINE_DIRTY_AMBIGUOUS (already dirty at dispatch baseline — a parallel session, not this run) are review-required and must NOT be counted against the run. (3) VERIFY RAN + PASSED — the deterministic verify gate (typecheck) ran OUTSIDE the coding agent after the run and passed; a run recorded as succeeded whose typecheck the reviewer cannot confirm passed is a CONCERN, and a run whose typecheck FAILED but was recorded succeeded is a GAP. (4) ATTRIBUTION CLEAN (the single-flight signal) — the run's edits are cleanly attributable to it in the captured change-set (files classed RUN_EXCLUSIVE or APPEARED_DURING_RUN), consistent with the single-flight lock having held for this dispatch. A change-set the capture could NOT cleanly attribute to the run — dominated by BASELINE_DIRTY_AMBIGUOUS overlap, or captured across a HEAD that moved mid-run — is a CONCERN the reviewer must resolve by hand before accepting the run, not a clean pass (single-flight is a hard runner floor, so this invariant reads the attribution the run actually recorded rather than re-proving the lock). (5) FAILURE DISPOSITION CORRECT — a failed/timed-out run's captured change-set is KEPT + FLAGGED for human triage (keep_and_flag), never silently reverted nor silently left as an un-recorded half-applied state; a failed run with no recorded change-set flag is a GAP (F-5 workspace-safety violation). (6) BOUNDARY DISCIPLINE — the dispatch stays at single-task depth: it dispatches ONE task, captures + verifies + records it, and applies onFailure. It does NOT re-decompose the plan (the build-decompose playbook owns the task graph), does NOT run MANY coding agents concurrently / design a concurrency scheduler / interleave the companion generation steps at scale (the scale playbook), and does NOT itself author schemas / fields / code (the coding agent does that at dispatch time). Evidence of re-decomposition, multi-agent scale orchestration, or the dispatcher authoring code itself is a CONCERN (scope creep out of the single-flight dispatch lane). (The checklist is declarative: nothing executes it; the deterministic gates and the creator's approval remain the floors.)\n",
|
|
24
27
|
"skillRefs": [
|
|
25
28
|
"journey-status",
|
|
26
29
|
"journey-approve",
|
|
27
30
|
"journey-run",
|
|
28
31
|
"journey-report"
|
|
29
|
-
]
|
|
30
|
-
"contextSources": [],
|
|
31
|
-
"suspendsForClarification": false,
|
|
32
|
-
"briefAdequacyGate": false,
|
|
33
|
-
"briefAdequacyExcludedSources": []
|
|
32
|
+
]
|
|
34
33
|
},
|
|
35
|
-
"executor": "
|
|
34
|
+
"executor": "composite",
|
|
35
|
+
"qualityGates": [
|
|
36
|
+
{
|
|
37
|
+
"ref": "dispatch-typecheck",
|
|
38
|
+
"kind": "deterministic_validator",
|
|
39
|
+
"validatorRef": "typecheck",
|
|
40
|
+
"required": true
|
|
41
|
+
}
|
|
42
|
+
],
|
|
36
43
|
"approval": "approve_before",
|
|
37
44
|
"budget": {
|
|
38
45
|
"maxInputTokens": 15000000,
|
|
@@ -96,8 +96,8 @@ Before scheduling anything:
|
|
|
96
96
|
bring-up tooling (deferred); the dogfood app already has a skeleton, so the scale
|
|
97
97
|
contract runs against an existing workspace.
|
|
98
98
|
|
|
99
|
-
//
|
|
100
|
-
//
|
|
99
|
+
// TODO CLI COMMAND: wildo journey status
|
|
100
|
+
// (read journey scope + the approved build plan + every task's dispatch state)
|
|
101
101
|
|
|
102
102
|
You **read** `build-plan`; you **write** no journey
|
|
103
103
|
artifact — the runner records each dispatched task's change-set + status on its
|
|
@@ -189,9 +189,8 @@ today's runner, see the caveat below.
|
|
|
189
189
|
arrive only with git worktree-per-agent isolation (the runner task in Step 5's
|
|
190
190
|
gap note). Until then, keep the input-ready *ordering* and serialize.
|
|
191
191
|
|
|
192
|
-
//
|
|
193
|
-
//
|
|
194
|
-
// runs its deterministic endpoint.
|
|
192
|
+
// TODO CLI COMMAND: wildo journey run <playbookRef>
|
|
193
|
+
// (trigger the scheduled wave; each coding slot invokes the single-flight dispatch contract, each generation step runs its deterministic endpoint)
|
|
195
194
|
|
|
196
195
|
## Step 4 — Authorize the fan-out (approve_before)
|
|
197
196
|
|
|
@@ -5,6 +5,10 @@
|
|
|
5
5
|
"intent": "Bottom-up build scale — the THIRD and final build-execution playbook, the pivot from dispatching ONE task safely (the single-flight dispatch contract) to running the build at SCALE: parallelism across several coding agents, the concurrency schedule, and interleaving the companion-owned generation steps concurrently with coding runs. Reads the approved build-plan (the ordered coding-agent task graph, each task carrying a target, ONE MetaWorkflow_FunctionalTopic, its skill(s), and prose prerequisite ordering) and the current journey state, and answers the SCALE questions the single-flight dispatch playbook deliberately left open: (1) derive the ready-SET (a wave / frontier of tasks whose prose prerequisites have ALL SUCCEEDED — not merely been attempted); (2) decide the parallelism degree (how many coding agents run at once) and the worktree-isolation model that keeps each concurrent run's change-set cleanly attributable; (3) schedule the waves respecting the DEPENDS_ON ordering the build-plan encodes; (4) interleave the deterministic companion-owned generation steps (labels / i18n, email templates, seeds) concurrently with coding runs at the points their inputs exist — those steps run through their deterministic companion endpoints, NOT the coding-agent single-flight lock, so they genuinely overlap coding runs; (5) reconcile wave completion across the concurrent runs (all tasks in the frontier SUCCEEDED before the next wave opens) and apply onFailure across siblings + downstream. Then advance to the next wave and loop. Each parallel slot INVOKES the single-flight dispatch contract (the build-dispatch playbook, upstream — select-next / context-pack / one ACP prompt turn / change-set capture / verify-outside / record + onFailure); this playbook does NOT re-specify those per-task mechanics and does NOT re-decompose the plan (the build-decompose playbook owns the task graph) and authors no schemas / no code. IMPORTANT HONESTY: the companion runner HARD-ENFORCES single-flight today (a run plan carries at most ONE coding-agent task; a concurrent dispatch is refused; the workspace-mutation lock + the lock-free cursor + the missing run-outcome observation loop all assume one dispatch at a time). So this v1 scale METHOD is the DECLARATIVE TARGET a runner-serializer slice will realize — on the current runner the waves DEGRADE to sequential single-flight dispatch. And even the deterministic companion-generation steps, though they do not take the coding single-flight lock, cannot SAFELY overlap an active coding run today: the coding run's change-set is captured as a whole-worktree time-window diff, so a generation step writing files inside that window is misattributed to the coding run (the same whole-worktree pollution that forbids two concurrent coding agents) — so the generation steps also serialize outside an active coding-capture window today, and genuine concurrency (coding-parallel OR generation-overlap) both arrive only with the git worktree-per-agent isolation runner task. v1 scaffold: a multi-CODING_AGENT run-completion serializer, git worktree-per-agent isolation, a run-outcome reconciler, and a cursor lock are companion-runner mechanism filed as runner tasks, NOT built here; a priority/work-stealing scheduler and cost-optimal packing are a later depth phase.",
|
|
6
6
|
"functionalTopics": [],
|
|
7
7
|
"preconditions": [
|
|
8
|
+
{
|
|
9
|
+
"kind": "phase_is",
|
|
10
|
+
"phase": "bottom_up"
|
|
11
|
+
},
|
|
8
12
|
{
|
|
9
13
|
"kind": "artifact_exists",
|
|
10
14
|
"selector": {
|
|
@@ -18,21 +22,24 @@
|
|
|
18
22
|
}
|
|
19
23
|
],
|
|
20
24
|
"outputs": [],
|
|
21
|
-
"stepOutputs": [],
|
|
22
25
|
"method": {
|
|
23
|
-
"guidance": "# Build Scale — Run the Build at Scale: Waves, Parallelism, Interleaved Generation (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology, and a deliberately honest one.** It is a\n> working first cut of the *scale* orchestration — derive a wave of ready tasks,\n> run several coding agents in parallel under an isolation model, interleave the\n> deterministic companion-generation steps, and reconcile wave completion. But\n> the companion runner **hard-enforces single-flight today**: it refuses a run\n> plan with more than one coding-agent task, refuses a second dispatch while one\n> is active, holds one workspace-mutation lock per run, and has no run-outcome\n> reconciler. So the concurrency described below is the **declarative target** a\n> runner-serializer slice will realize. **On the current runner the waves\n> degrade to sequential single-flight dispatch** — read the \"What the runner\n> actually does today\" section before you assume anything ran in parallel. Do\n> not overclaim concurrency the runner cannot do.\n\n## Where you are in the journey\n\nThis is the **third and final build-execution playbook** — the pivot from\n**dispatching one task safely** (the build-dispatch playbook's single-flight\ncontract) to **running the build at scale**. It runs in the **bottom-up phase**,\nafter the build plan exists (`artifact_exists build-plan`) and the foundation\nstep has authored the app's config and skeleton. You\nare not re-opening the decomposition here, and you are not re-specifying how one\ntask dispatches — you are deciding **how many** tasks run **concurrently** and\n**safely**, in **what order**, with the companion-generation steps interleaved.\n\nUpstream: the **build-decompose** playbook produced the ordered task graph you\nschedule; the **build-dispatch** playbook defined how ONE task dispatches\nsafely — you **invoke that contract per parallel slot**, you do not re-author\nit. **You author neither of those concerns** — see the boundary section.\n\n## What this playbook does\n\nYou are the **scale orchestrator**. This playbook reads the approved build plan\nand the current journey state and answers, across the *whole* build: *\"which set\nof tasks is ready to run now, how many run at once and on what isolation, when\ndo the deterministic generation steps run, and when has a wave actually\nfinished?\"* You do **not** produce a new journey artifact — the observable\nresult of the build is the per-task change-sets + task statuses the runner\nrecords on the task rows (the build-dispatch playbook's mechanism), not a\nschedule artifact authored here (see \"What you emit\"). You do **not** decompose\nthe plan, re-specify the per-task dispatch mechanics, author any schema, or\nwrite any code.\n\n## The scale contract — you sequence waves, the dispatch playbook runs each slot\n\nMost of the *per-task* mechanism is **not yours**: selecting one task,\ncomposing its context pack, running one prompt turn against the coding agent over\nthe Agent Client Protocol (answering its permission requests within the declared\nceiling), capturing the change-set, running the verify hook, holding the\nsingle-flight lock, enforcing the budget floor — all of that is the **build-dispatch** contract, which each\nparallel slot invokes. Your method here is the **declarative concurrency\nrecipe** the runner (or a future runner-serializer) interprets: *which set* of\ntasks is ready, *how many* run at once, *how* they are isolated, *when* the\ndeterministic generation steps interleave, and *when* a wave is done. Do not\nhand-drive git, do not compose a dispatch prompt, do not re-implement the\nsingle-flight capture — invoke the dispatch contract per slot and let it own\nthose.\n\n## Read state first — no artifact to write\n\nThis playbook is **idempotent** and, on a re-run, *advances the schedule by one\nwave* (and, on today's single-flight runner, by one task within that wave).\nBefore scheduling anything:\n\n1. Read the current journey state and scope through the `journey-status` skill\n (it owns the read; do not re-derive it here). Confirm the **build plan** is\n present and approved and the **foundation** ran. For each build-plan task,\n read its dispatch state from its task row — **not yet dispatched**,\n **dispatched-and-succeeded** (a captured change-set + a passed verify),\n **dispatched-and-failed** (a captured change-set but a failed/timed-out run\n or a failed verify), or **in-flight**. This full state — not just \"has a\n change-set\" — is what the wave derivation keys on (under `keep_and_flag` a\n *failed* task also has a captured change-set, so presence of a change-set\n alone never means \"done\").\n2. Read the approved **build plan** (`build-plan` — the ordered task graph, with\n each task's prose prerequisite references). It is your work list.\n\n That there is an application to dispatch into is answered by the committed\n `./wildo.saas.config.ts` and skeleton, not by a journey artifact. (A\n `foundation-manifest` played that role until 2026-08-25 and was retired with the\n app-creation verification/digest aspect.) The honest limitation the foundation step\n carries still applies: on-disk skeleton materialization depends on greenfield\n bring-up tooling (deferred); the dogfood app already has a skeleton, so the scale\n contract runs against an existing workspace.\n\n// Operator status: `wildo context journey` (phase + board + runs in flight); per-task landed\n// state is read from git by the runner.\n\nYou **read** `build-plan`; you **write** no journey\nartifact — the runner records each dispatched task's change-set + status on its\nrow.\n\n## Step 1 — Derive the ready-set (the wave / frontier)\n\nWalk the build plan and compute the **frontier**: the set of tasks that are\n**not yet dispatched** (or previously-**failed** tasks cleared for retry) and\nwhose prose prerequisites have **all SUCCEEDED**. That set is the next **wave**.\n\n- **A prerequisite must have SUCCEEDED, not merely been attempted.** A task\n enters the frontier only when every task it depends on is\n dispatched-and-succeeded (verify passed). A prerequisite that is\n dispatched-and-**failed** (its change-set flagged for triage under\n `keep_and_flag`), still **in-flight**, or un-run does **not** satisfy the\n dependency — its dependents stay **out of the frontier** until it succeeds.\n This is the U13b readiness discipline, lifted to a set: do not open a wave on\n a schema whose run has not verified.\n- **The wave respects the build-plan ordering.** The build-decompose playbook\n encoded the DEPENDS_ON edges (the per-resource stage order schema → config →\n ui-behavior → spec, the cross-topic edges, relationship-after-endpoints); the\n frontier is exactly the tasks with no unsatisfied edge remaining. You do not\n re-derive or re-order those edges — you read them and compute the ready-set.\n- **An empty frontier is a terminal state.** If no task is ready — every task\n has succeeded, or the only undispatched tasks are blocked behind an\n unresolved failure — the build is done (or blocked on a flagged failure):\n report it and stop. An empty build plan is the same.\n\n## Step 2 — Decide the parallelism degree + the worktree-isolation model\n\nFor the frontier, decide **how many** coding agents run at once and **on what\nisolation**. This is the core scale decision, and it is bounded by a hard\nsafety constraint, not just throughput:\n\n- **Change-set attribution requires isolation.** The dispatch contract captures\n each run's change-set by diffing the worktree around the run and attributing\n every file as `RUN_EXCLUSIVE`, `APPEARED_DURING_RUN`, or\n `BASELINE_DIRTY_AMBIGUOUS`. **Two coding agents mutating the SAME worktree\n concurrently make every touched file `BASELINE_DIRTY_AMBIGUOUS`** — each run\n looks like it started against a tree the other was dirtying — which\n **destroys per-run attribution**. So real parallelism needs one of:\n - **git worktree-per-agent isolation** — each concurrent coding agent runs in\n its own git worktree (a disjoint checkout of the same repo), so each run's\n change-set is captured against a tree only it mutates; the worktrees are\n reconciled/merged after the wave. This is the general answer.\n - **module / resource partitioning** — schedule concurrent agents only onto\n tasks whose targets touch **disjoint file sets** (different modules /\n resources), so even on one shared worktree no two runs collide. This is the\n cheaper answer when the frontier naturally partitions by module.\n - **or keep coding single-flight** and only parallelise the deterministic\n companion-generation steps (Step 3), which are not coding-locked.\n- **Pick the degree deliberately, not maximally.** At scaffold depth prefer a\n small degree (or a module partition) over max fan-out — cost-optimal packing,\n a priority / work-stealing scheduler, and backoff are a later depth phase, not\n this scaffold. State the isolation model you chose; a wave with degree > 1 and\n **no** isolation answer is unsafe (the reviewer rubric flags it as a GAP).\n\n## Step 3 — Interleave the deterministic companion-generation steps\n\nThe build plan carries **companion-owned generation steps** — labels / i18n,\nemail templates, seeds — as tasks. These are **deterministic companion\nendpoints**, not coding-agent dispatches: they do **not** contend for the\ncoding single-flight lock. It is tempting to conclude they can freely run\n*alongside* a coding run — but there is a subtlety that makes that unsafe on\ntoday's runner, see the caveat below.\n\n- **Run each generation step at its input-ready point.** A labels/i18n step runs\n after the resources it labels exist; an email step after its templates'\n definition surfaces exist; a seed step after the resources it seeds exist.\n Schedule each at its input-ready point in the wave sequence — do not block a\n coding wave on them and do not run them before their inputs exist. (The\n *ordering* is what matters here; the *concurrency* is deferred — see the\n caveat.)\n- **Route them to their deterministic endpoint, not the coding lane.** Do not\n dispatch a coding agent for a labels/email/seed step — it has a deterministic\n companion generator. Treating a generation step as a coding dispatch is scope\n creep the reviewer flags.\n- **CAVEAT — no attribution-safe overlap with an active coding run today.** The\n coding run's change-set is captured as a **whole-worktree time-window diff**\n (every tracked-dirty + untracked file in the window). So a generation step\n writing label / email / seed files **while a coding dispatch is capturing** is\n misattributed to that coding run — its files show up as the coding run's own\n edits. This is the *same* whole-worktree pollution that forbids two concurrent\n coding agents (Step 2), and it applies identically to coding + generation. So\n on today's runner the generation steps must **also** be serialized to run\n **outside** an active coding-capture window (i.e. between coding runs). Genuine\n overlap — generation alongside coding, and coding alongside coding — both\n arrive only with git worktree-per-agent isolation (the runner task in Step 5's\n gap note). Until then, keep the input-ready *ordering* and serialize.\n\n// The trigger is the companion's run route (`POST /api/companion/playbooks/<ref>/run`) — no CLI\n// trigger yet. Each coding slot invokes the single-flight dispatch contract; each generation step\n// runs its deterministic endpoint.\n\n## Step 4 — Authorize the fan-out (approve_before)\n\nFanning out **several** coding agents that **mutate the application workspace**\nis the highest-stakes action in the journey. This playbook's approval posture is\n`approve_before`: the scale run is authorized **before** it touches the tree.\nSettle the exact pending Authority Request through the `journey-approve` skill; never start\nthe fan-out on your own judgment.\n\n- Under the **GUIDED** autonomy preset the gate is verbatim; under\n **YOLO_LIGHT** it downgrades to a post-hoc result review; under **YOLO** it is\n auto (the non-bypassable **budget floor** — per-playbook and per-journey\n run/wall-time ceilings — is the guardrail no preset can lift).\n- **v1 gate granularity (be honest about the floor's reach).** The approval gate\n is currently **playbook-scoped for the journey**, not scoped to a single wave:\n the first authorization of this scale playbook admits its subsequent runs too\n (bounded by the run-count budget floor), rather than re-prompting per wave. So\n `approve_before` here means \"the creator authorizes the **scale loop** before\n any task mutates the workspace\" — a real pre-fan-out floor. A per-wave,\n single-use gate is a deferred runner posture; until it lands, the budget\n ceiling + the per-task change-set capture + the verify gate bound the\n authorized loop.\n\n## Step 5 — Reconcile wave completion, then advance\n\nA wave is done only when **every task in the frontier reached a terminal\nSUCCEEDED outcome** (change-set captured + verify passed) or is explicitly held\nas a blocked / flagged failure. Only then does the next frontier open (Step 1).\n\n- **Do not open the next wave on an unfinished one.** Advancing while a wave's\n tasks are still in-flight, or with an unreconciled failure, risks a downstream\n task building on an unfinished prerequisite. Reconcile first.\n- **Failure disposition across siblings + downstream** — this playbook's\n `onFailure` is **`keep_and_flag`**: a failed/timed-out task keeps its captured\n change-set flagged for human triage (never silently reverted, never an\n un-recorded half-applied state). Its already-dispatched **siblings** in the\n same wave are left to complete; its **dependents** in later waves stay\n **blocked** (Step 1) until it is triaged and re-dispatched successfully.\n Triage is a human decision: keep + fix forward, unwind the flagged change-set\n by hand, or re-dispatch once the blocker is resolved. This playbook does not\n auto-retry a failed task (automated retry / backoff is a deferred build-loop\n resilience concern).\n\n> **Why keep_and_flag, not revert_changeset (a v1 boundary).** Reverting a\n> failed run's edits is a *mutating* git op, deliberately **outside** the\n> read-only change-set carve-out the dispatch lane observes. So `keep_and_flag`\n> is both the correct F-5 workspace-safety posture and the behavior the runner\n> enforces today; a `revert_changeset` path is a deliberate later boundary.\n\nThen **loop**: on the next run, `journey-status` reflects the just-completed\nwave's outcomes, and you derive the next frontier (Step 1). Close a significant\nstretch of the build with a `journey-report` summary — which waves ran, which\nchange-sets landed, what verify said, which generation steps interleaved, and\nany failed task left flagged for triage.\n\n## What the runner actually does today (do not overclaim)\n\nBe honest with the creator about the gap between this method and the runner:\n\n- **The runner enforces single-flight.** It refuses a run plan carrying more\n than one coding-agent task, refuses a second dispatch while one is active, and\n holds one workspace-mutation lock per background run. So a wave with\n parallelism degree > 1 is **not** realizable on today's runner — the wave\n **degrades to sequential single-flight dispatch** (repeated invocation of the\n build-dispatch contract, one task at a time, in frontier order). The frontier\n math, the readiness discipline, and the reconciliation are all still correct\n and useful sequentially — you just do not get concurrency yet.\n- **No overlap is attribution-safe today — not even a companion-generation\n step.** The generation endpoints are not coding-locked, but the coding\n change-set capture is a whole-worktree time-window diff, so a generation step\n writing files while a coding dispatch is capturing is misattributed to that\n run (Step 3's caveat). So the generation steps **also** serialize outside an\n active coding-capture window: their input-ready *ordering* holds, only the\n *concurrency* is deferred. Safe overlap of generation-with-coding, and\n coding-with-coding, both require git worktree-per-agent isolation.\n- **The concurrency this method describes is the declarative target** for a\n runner-serializer slice (multi-coding-agent run-completion serialization,\n git worktree-per-agent isolation, a run-outcome reconciler, and a cursor lock)\n — filed as runner tasks, **not** built by this scaffold playbook. Until they\n land, run the waves sequentially and do not claim a parallel run (or a\n generation-alongside-coding overlap) happened when it did not.\n\n## Scaffold-depth boundary (owned by a sibling, or deferred to a later phase)\n\nKeep this playbook at **scale-orchestration depth**. Explicitly **out of scope\nhere**:\n\n- **Re-decomposition.** You do NOT split modules/resources into tasks, re-order\n the graph, or add tasks — the **build-decompose** playbook owns the task\n graph. You read it and schedule from it.\n- **The per-task dispatch contract.** You do NOT re-specify single-flight\n locking, context-pack composition, change-set capture, or the verify hook —\n the **build-dispatch** playbook owns \"how ONE task dispatches safely\", and\n each parallel slot **invokes** that contract. If you catch yourself describing\n how a single task captures its change-set, stop — that is the dispatch\n playbook.\n- **The runner-serializer mechanism.** The multi-coding-agent serializer, git\n worktree-per-agent provisioning, the run-outcome reconciler, and the cursor\n lock are **companion-runner mechanism**, filed as runner tasks — this\n declarative method does not build them.\n- **A priority / work-stealing scheduler + cost-optimal packing.** Deciding an\n optimal task ordering within a band, work-stealing across idle slots, backoff,\n and cost-optimal packing are a later depth phase — the v1 scaffold picks a\n small parallelism degree (or a module partition) and a simple frontier order.\n- **A `revert_changeset` failure path.** Deferred; `keep_and_flag` is the v1\n disposition.\n- **Auto-executed reviewer checklist.** The scale-soundness checklist ships\n **declarative** — the deterministic typecheck gate runs automatically; nothing\n executes the checklist prose (rubric-only judge gates were retired at the\n flexible-intelligence hard cut). Do not assume it auto-ran.\n- **Schema / field authoring + code generation.** The **coding agents** author\n fields, schemas, ui-behavior, and code at dispatch time — never the\n orchestrator.\n\nIf you find yourself designing how ONE task dispatches safely rather than how\nMANY tasks are scheduled + reconciled, stop — that is the build-dispatch\nplaybook.\n\n## What you emit\n\n**No journey artifact.** This is a pure-orchestration playbook: the observable\nresult of the build — each task's **change-set** (files touched, attributed,\nsummarized) and **status** — is materialized by the runner on the dispatched\ntask rows (the build-dispatch playbook's mechanism), not authored here. A\nseparate schedule / wave-log artifact family is deliberately not added: the task\nrows already *are* the dispatch record and a second home for the same record\nwould drift (a typed wave-schedule / run-ledger contract is a filed later-phase\nitem). The creator authorizes the scale run (`approve_before`) before it fans\nout, and reviews the recorded change-sets + verify outcomes after — wave by\nwave, until the build plan is fully dispatched.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state,\n scope, and budget; confirm the build plan is approved and the foundation ran,\n and read every task's dispatch state to compute the frontier.\n- `.claude/skills/journey-approve/SKILL.md` — relay the exact pre-fan-out Authority Request\n gate decision that authorizes the workspace-mutating fan-out (never\n self-approve).\n- `.claude/skills/journey-run/SKILL.md` — trigger a scheduled wave; each coding\n slot invokes the single-flight dispatch contract and each deterministic\n generation step runs its companion endpoint.\n- `.claude/skills/journey-report/SKILL.md` — summarize a stretch of the build:\n which waves ran, which change-sets landed, what verify said, and any failed\n task left flagged for triage.\n\n## Reviewer checklist — `scale-schedule-sound`\n\nFormerly authored as an `llm_judge` quality gate; the generic rubric-only gate kind was retired at the flexible-intelligence hard cut (judgment now runs only through a compiled Evaluation Treatment). The checklist itself is creator-facing review guidance and is kept here, verbatim, minus the retired runner's closing sentence:\n\nJudge whether the SCALE orchestration ran the build soundly — the trust-but-verify reviewer pass over how MANY tasks were scheduled, parallelised, and reconciled, WITHOUT straying into how ONE task dispatches (that is the build-dispatch playbook's rubric) or how the plan was decomposed (the build-decompose playbook's). Assess six invariants and mark each PASS / CONCERN / GAP with a one-line evidence note. (1) WAVE READINESS — every task dispatched in a wave had ALL its prose prerequisites already SUCCEEDED (dispatched-and-verified), not merely attempted; a task dispatched while a prerequisite was un-run, in-flight, or dispatched-and-FAILED is a GAP (the build stage ran against a missing prerequisite). A prerequisite whose run FAILED (its change-set flagged under keep_and_flag) does NOT satisfy the dependency — its dependents must stay blocked, and dispatching them anyway is a GAP. (2) PARALLELISM SAFETY / ATTRIBUTION — the concurrent coding runs in a wave were isolated so each run's change-set is cleanly attributable (files RUN_EXCLUSIVE / APPEARED_DURING_RUN per run), via git worktree-per-agent isolation OR a module/resource partition that puts every concurrent agent on a DISJOINT file set. Two concurrent coding agents mutating the SAME worktree — which makes every touched file BASELINE_DIRTY_AMBIGUOUS and destroys per-run attribution — is a GAP (the single-flight floor was bypassed without an isolation answer). Note the honest floor: the runner enforces single-flight today, so on the current runner a 'wave' degrades to SEQUENTIAL single-flight dispatch and this invariant reads whether the METHOD declared a sound isolation model, not whether concurrency actually ran. (3) COMPANION-GENERATION INTERLEAVE — the deterministic companion-owned generation steps (labels / i18n, email templates, seeds) ran through their deterministic companion endpoints AFTER the resources / modules whose output they consume existed, at the right point in the schedule order; a generation step ordered before its inputs exist, or a missing generation step for authored surfaces, is a CONCERN; treating a deterministic generation step as a coding-agent dispatch (dispatching an agent for it) is a CONCERN. Note the honest floor: the generation steps do NOT take the coding single-flight lock, but the coding change-set capture is a whole-worktree time-window diff, so a generation step writing files WHILE a coding dispatch is capturing is misattributed to that coding run — so on today's runner the generation steps also serialize outside an active coding-capture window, and this invariant reads whether they ran at the right point in the ORDER, not whether they truly overlapped a coding run (safe overlap needs worktree isolation). (4) WAVE-COMPLETION RECONCILIATION — the next wave opened only after every task in the current frontier reached a terminal SUCCEEDED outcome (or was explicitly held as a blocked / flagged failure); advancing the schedule while a wave's tasks were still in-flight or with an unreconciled failure is a GAP (a downstream task could build on an unfinished prerequisite). (5) FAILURE DISPOSITION ACROSS SIBLINGS + DOWNSTREAM — a failed / timed-out task in a wave kept its captured change-set flagged for human triage (keep_and_flag), its already-dispatched siblings in the same wave were left to complete, and its DEPENDENTS in later waves stayed blocked until it was triaged and re-dispatched successfully; a failed task whose dependents were dispatched anyway, or a failure silently reverted / left un-recorded, is a GAP (F-5 workspace-safety violation). (6) BOUNDARY DISCIPLINE — the orchestration stays at SCALE depth: it derives ready-sets, schedules waves, sets the parallelism + isolation model, interleaves the companion-generation steps, and reconciles completion. It does NOT re-decompose the plan (the build-decompose playbook owns the task graph), does NOT re-specify the per-task dispatch mechanics (single-flight lock / context-pack / change-set capture / verify — the build-dispatch playbook owns those; the scale orchestrator INVOKES that contract per slot), and does NOT itself author schemas / fields / code (the coding agents do that at dispatch time). Evidence of re-decomposition, re-authoring the single-task dispatch contract, or the orchestrator authoring code itself is a CONCERN (scope creep out of the scale lane). (The checklist is declarative: nothing executes it; the deterministic gates and the creator's approval remain the floors.)\n",
|
|
26
|
+
"guidance": "# Build Scale — Run the Build at Scale: Waves, Parallelism, Interleaved Generation (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology, and a deliberately honest one.** It is a\n> working first cut of the *scale* orchestration — derive a wave of ready tasks,\n> run several coding agents in parallel under an isolation model, interleave the\n> deterministic companion-generation steps, and reconcile wave completion. But\n> the companion runner **hard-enforces single-flight today**: it refuses a run\n> plan with more than one coding-agent task, refuses a second dispatch while one\n> is active, holds one workspace-mutation lock per run, and has no run-outcome\n> reconciler. So the concurrency described below is the **declarative target** a\n> runner-serializer slice will realize. **On the current runner the waves\n> degrade to sequential single-flight dispatch** — read the \"What the runner\n> actually does today\" section before you assume anything ran in parallel. Do\n> not overclaim concurrency the runner cannot do.\n\n## Where you are in the journey\n\nThis is the **third and final build-execution playbook** — the pivot from\n**dispatching one task safely** (the build-dispatch playbook's single-flight\ncontract) to **running the build at scale**. It runs in the **bottom-up phase**,\nafter the build plan exists (`artifact_exists build-plan`) and the foundation\nstep has authored the app's config and skeleton. You\nare not re-opening the decomposition here, and you are not re-specifying how one\ntask dispatches — you are deciding **how many** tasks run **concurrently** and\n**safely**, in **what order**, with the companion-generation steps interleaved.\n\nUpstream: the **build-decompose** playbook produced the ordered task graph you\nschedule; the **build-dispatch** playbook defined how ONE task dispatches\nsafely — you **invoke that contract per parallel slot**, you do not re-author\nit. **You author neither of those concerns** — see the boundary section.\n\n## What this playbook does\n\nYou are the **scale orchestrator**. This playbook reads the approved build plan\nand the current journey state and answers, across the *whole* build: *\"which set\nof tasks is ready to run now, how many run at once and on what isolation, when\ndo the deterministic generation steps run, and when has a wave actually\nfinished?\"* You do **not** produce a new journey artifact — the observable\nresult of the build is the per-task change-sets + task statuses the runner\nrecords on the task rows (the build-dispatch playbook's mechanism), not a\nschedule artifact authored here (see \"What you emit\"). You do **not** decompose\nthe plan, re-specify the per-task dispatch mechanics, author any schema, or\nwrite any code.\n\n## The scale contract — you sequence waves, the dispatch playbook runs each slot\n\nMost of the *per-task* mechanism is **not yours**: selecting one task,\ncomposing its context pack, running one prompt turn against the coding agent over\nthe Agent Client Protocol (answering its permission requests within the declared\nceiling), capturing the change-set, running the verify hook, holding the\nsingle-flight lock, enforcing the budget floor — all of that is the **build-dispatch** contract, which each\nparallel slot invokes. Your method here is the **declarative concurrency\nrecipe** the runner (or a future runner-serializer) interprets: *which set* of\ntasks is ready, *how many* run at once, *how* they are isolated, *when* the\ndeterministic generation steps interleave, and *when* a wave is done. Do not\nhand-drive git, do not compose a dispatch prompt, do not re-implement the\nsingle-flight capture — invoke the dispatch contract per slot and let it own\nthose.\n\n## Read state first — no artifact to write\n\nThis playbook is **idempotent** and, on a re-run, *advances the schedule by one\nwave* (and, on today's single-flight runner, by one task within that wave).\nBefore scheduling anything:\n\n1. Read the current journey state and scope through the `journey-status` skill\n (it owns the read; do not re-derive it here). Confirm the **build plan** is\n present and approved and the **foundation** ran. For each build-plan task,\n read its dispatch state from its task row — **not yet dispatched**,\n **dispatched-and-succeeded** (a captured change-set + a passed verify),\n **dispatched-and-failed** (a captured change-set but a failed/timed-out run\n or a failed verify), or **in-flight**. This full state — not just \"has a\n change-set\" — is what the wave derivation keys on (under `keep_and_flag` a\n *failed* task also has a captured change-set, so presence of a change-set\n alone never means \"done\").\n2. Read the approved **build plan** (`build-plan` — the ordered task graph, with\n each task's prose prerequisite references). It is your work list.\n\n That there is an application to dispatch into is answered by the committed\n `./wildo.saas.config.ts` and skeleton, not by a journey artifact. (A\n `foundation-manifest` played that role until 2026-08-25 and was retired with the\n app-creation verification/digest aspect.) The honest limitation the foundation step\n carries still applies: on-disk skeleton materialization depends on greenfield\n bring-up tooling (deferred); the dogfood app already has a skeleton, so the scale\n contract runs against an existing workspace.\n\n// TODO CLI COMMAND: wildo journey status\n// (read journey scope + the approved build plan + every task's dispatch state)\n\nYou **read** `build-plan`; you **write** no journey\nartifact — the runner records each dispatched task's change-set + status on its\nrow.\n\n## Step 1 — Derive the ready-set (the wave / frontier)\n\nWalk the build plan and compute the **frontier**: the set of tasks that are\n**not yet dispatched** (or previously-**failed** tasks cleared for retry) and\nwhose prose prerequisites have **all SUCCEEDED**. That set is the next **wave**.\n\n- **A prerequisite must have SUCCEEDED, not merely been attempted.** A task\n enters the frontier only when every task it depends on is\n dispatched-and-succeeded (verify passed). A prerequisite that is\n dispatched-and-**failed** (its change-set flagged for triage under\n `keep_and_flag`), still **in-flight**, or un-run does **not** satisfy the\n dependency — its dependents stay **out of the frontier** until it succeeds.\n This is the U13b readiness discipline, lifted to a set: do not open a wave on\n a schema whose run has not verified.\n- **The wave respects the build-plan ordering.** The build-decompose playbook\n encoded the DEPENDS_ON edges (the per-resource stage order schema → config →\n ui-behavior → spec, the cross-topic edges, relationship-after-endpoints); the\n frontier is exactly the tasks with no unsatisfied edge remaining. You do not\n re-derive or re-order those edges — you read them and compute the ready-set.\n- **An empty frontier is a terminal state.** If no task is ready — every task\n has succeeded, or the only undispatched tasks are blocked behind an\n unresolved failure — the build is done (or blocked on a flagged failure):\n report it and stop. An empty build plan is the same.\n\n## Step 2 — Decide the parallelism degree + the worktree-isolation model\n\nFor the frontier, decide **how many** coding agents run at once and **on what\nisolation**. This is the core scale decision, and it is bounded by a hard\nsafety constraint, not just throughput:\n\n- **Change-set attribution requires isolation.** The dispatch contract captures\n each run's change-set by diffing the worktree around the run and attributing\n every file as `RUN_EXCLUSIVE`, `APPEARED_DURING_RUN`, or\n `BASELINE_DIRTY_AMBIGUOUS`. **Two coding agents mutating the SAME worktree\n concurrently make every touched file `BASELINE_DIRTY_AMBIGUOUS`** — each run\n looks like it started against a tree the other was dirtying — which\n **destroys per-run attribution**. So real parallelism needs one of:\n - **git worktree-per-agent isolation** — each concurrent coding agent runs in\n its own git worktree (a disjoint checkout of the same repo), so each run's\n change-set is captured against a tree only it mutates; the worktrees are\n reconciled/merged after the wave. This is the general answer.\n - **module / resource partitioning** — schedule concurrent agents only onto\n tasks whose targets touch **disjoint file sets** (different modules /\n resources), so even on one shared worktree no two runs collide. This is the\n cheaper answer when the frontier naturally partitions by module.\n - **or keep coding single-flight** and only parallelise the deterministic\n companion-generation steps (Step 3), which are not coding-locked.\n- **Pick the degree deliberately, not maximally.** At scaffold depth prefer a\n small degree (or a module partition) over max fan-out — cost-optimal packing,\n a priority / work-stealing scheduler, and backoff are a later depth phase, not\n this scaffold. State the isolation model you chose; a wave with degree > 1 and\n **no** isolation answer is unsafe (the reviewer rubric flags it as a GAP).\n\n## Step 3 — Interleave the deterministic companion-generation steps\n\nThe build plan carries **companion-owned generation steps** — labels / i18n,\nemail templates, seeds — as tasks. These are **deterministic companion\nendpoints**, not coding-agent dispatches: they do **not** contend for the\ncoding single-flight lock. It is tempting to conclude they can freely run\n*alongside* a coding run — but there is a subtlety that makes that unsafe on\ntoday's runner, see the caveat below.\n\n- **Run each generation step at its input-ready point.** A labels/i18n step runs\n after the resources it labels exist; an email step after its templates'\n definition surfaces exist; a seed step after the resources it seeds exist.\n Schedule each at its input-ready point in the wave sequence — do not block a\n coding wave on them and do not run them before their inputs exist. (The\n *ordering* is what matters here; the *concurrency* is deferred — see the\n caveat.)\n- **Route them to their deterministic endpoint, not the coding lane.** Do not\n dispatch a coding agent for a labels/email/seed step — it has a deterministic\n companion generator. Treating a generation step as a coding dispatch is scope\n creep the reviewer flags.\n- **CAVEAT — no attribution-safe overlap with an active coding run today.** The\n coding run's change-set is captured as a **whole-worktree time-window diff**\n (every tracked-dirty + untracked file in the window). So a generation step\n writing label / email / seed files **while a coding dispatch is capturing** is\n misattributed to that coding run — its files show up as the coding run's own\n edits. This is the *same* whole-worktree pollution that forbids two concurrent\n coding agents (Step 2), and it applies identically to coding + generation. So\n on today's runner the generation steps must **also** be serialized to run\n **outside** an active coding-capture window (i.e. between coding runs). Genuine\n overlap — generation alongside coding, and coding alongside coding — both\n arrive only with git worktree-per-agent isolation (the runner task in Step 5's\n gap note). Until then, keep the input-ready *ordering* and serialize.\n\n// TODO CLI COMMAND: wildo journey run <playbookRef>\n// (trigger the scheduled wave; each coding slot invokes the single-flight dispatch contract, each generation step runs its deterministic endpoint)\n\n## Step 4 — Authorize the fan-out (approve_before)\n\nFanning out **several** coding agents that **mutate the application workspace**\nis the highest-stakes action in the journey. This playbook's approval posture is\n`approve_before`: the scale run is authorized **before** it touches the tree.\nSettle the exact pending Authority Request through the `journey-approve` skill; never start\nthe fan-out on your own judgment.\n\n- Under the **GUIDED** autonomy preset the gate is verbatim; under\n **YOLO_LIGHT** it downgrades to a post-hoc result review; under **YOLO** it is\n auto (the non-bypassable **budget floor** — per-playbook and per-journey\n run/wall-time ceilings — is the guardrail no preset can lift).\n- **v1 gate granularity (be honest about the floor's reach).** The approval gate\n is currently **playbook-scoped for the journey**, not scoped to a single wave:\n the first authorization of this scale playbook admits its subsequent runs too\n (bounded by the run-count budget floor), rather than re-prompting per wave. So\n `approve_before` here means \"the creator authorizes the **scale loop** before\n any task mutates the workspace\" — a real pre-fan-out floor. A per-wave,\n single-use gate is a deferred runner posture; until it lands, the budget\n ceiling + the per-task change-set capture + the verify gate bound the\n authorized loop.\n\n## Step 5 — Reconcile wave completion, then advance\n\nA wave is done only when **every task in the frontier reached a terminal\nSUCCEEDED outcome** (change-set captured + verify passed) or is explicitly held\nas a blocked / flagged failure. Only then does the next frontier open (Step 1).\n\n- **Do not open the next wave on an unfinished one.** Advancing while a wave's\n tasks are still in-flight, or with an unreconciled failure, risks a downstream\n task building on an unfinished prerequisite. Reconcile first.\n- **Failure disposition across siblings + downstream** — this playbook's\n `onFailure` is **`keep_and_flag`**: a failed/timed-out task keeps its captured\n change-set flagged for human triage (never silently reverted, never an\n un-recorded half-applied state). Its already-dispatched **siblings** in the\n same wave are left to complete; its **dependents** in later waves stay\n **blocked** (Step 1) until it is triaged and re-dispatched successfully.\n Triage is a human decision: keep + fix forward, unwind the flagged change-set\n by hand, or re-dispatch once the blocker is resolved. This playbook does not\n auto-retry a failed task (automated retry / backoff is a deferred build-loop\n resilience concern).\n\n> **Why keep_and_flag, not revert_changeset (a v1 boundary).** Reverting a\n> failed run's edits is a *mutating* git op, deliberately **outside** the\n> read-only change-set carve-out the dispatch lane observes. So `keep_and_flag`\n> is both the correct F-5 workspace-safety posture and the behavior the runner\n> enforces today; a `revert_changeset` path is a deliberate later boundary.\n\nThen **loop**: on the next run, `journey-status` reflects the just-completed\nwave's outcomes, and you derive the next frontier (Step 1). Close a significant\nstretch of the build with a `journey-report` summary — which waves ran, which\nchange-sets landed, what verify said, which generation steps interleaved, and\nany failed task left flagged for triage.\n\n## What the runner actually does today (do not overclaim)\n\nBe honest with the creator about the gap between this method and the runner:\n\n- **The runner enforces single-flight.** It refuses a run plan carrying more\n than one coding-agent task, refuses a second dispatch while one is active, and\n holds one workspace-mutation lock per background run. So a wave with\n parallelism degree > 1 is **not** realizable on today's runner — the wave\n **degrades to sequential single-flight dispatch** (repeated invocation of the\n build-dispatch contract, one task at a time, in frontier order). The frontier\n math, the readiness discipline, and the reconciliation are all still correct\n and useful sequentially — you just do not get concurrency yet.\n- **No overlap is attribution-safe today — not even a companion-generation\n step.** The generation endpoints are not coding-locked, but the coding\n change-set capture is a whole-worktree time-window diff, so a generation step\n writing files while a coding dispatch is capturing is misattributed to that\n run (Step 3's caveat). So the generation steps **also** serialize outside an\n active coding-capture window: their input-ready *ordering* holds, only the\n *concurrency* is deferred. Safe overlap of generation-with-coding, and\n coding-with-coding, both require git worktree-per-agent isolation.\n- **The concurrency this method describes is the declarative target** for a\n runner-serializer slice (multi-coding-agent run-completion serialization,\n git worktree-per-agent isolation, a run-outcome reconciler, and a cursor lock)\n — filed as runner tasks, **not** built by this scaffold playbook. Until they\n land, run the waves sequentially and do not claim a parallel run (or a\n generation-alongside-coding overlap) happened when it did not.\n\n## Scaffold-depth boundary (owned by a sibling, or deferred to a later phase)\n\nKeep this playbook at **scale-orchestration depth**. Explicitly **out of scope\nhere**:\n\n- **Re-decomposition.** You do NOT split modules/resources into tasks, re-order\n the graph, or add tasks — the **build-decompose** playbook owns the task\n graph. You read it and schedule from it.\n- **The per-task dispatch contract.** You do NOT re-specify single-flight\n locking, context-pack composition, change-set capture, or the verify hook —\n the **build-dispatch** playbook owns \"how ONE task dispatches safely\", and\n each parallel slot **invokes** that contract. If you catch yourself describing\n how a single task captures its change-set, stop — that is the dispatch\n playbook.\n- **The runner-serializer mechanism.** The multi-coding-agent serializer, git\n worktree-per-agent provisioning, the run-outcome reconciler, and the cursor\n lock are **companion-runner mechanism**, filed as runner tasks — this\n declarative method does not build them.\n- **A priority / work-stealing scheduler + cost-optimal packing.** Deciding an\n optimal task ordering within a band, work-stealing across idle slots, backoff,\n and cost-optimal packing are a later depth phase — the v1 scaffold picks a\n small parallelism degree (or a module partition) and a simple frontier order.\n- **A `revert_changeset` failure path.** Deferred; `keep_and_flag` is the v1\n disposition.\n- **Auto-executed reviewer checklist.** The scale-soundness checklist ships\n **declarative** — the deterministic typecheck gate runs automatically; nothing\n executes the checklist prose (rubric-only judge gates were retired at the\n flexible-intelligence hard cut). Do not assume it auto-ran.\n- **Schema / field authoring + code generation.** The **coding agents** author\n fields, schemas, ui-behavior, and code at dispatch time — never the\n orchestrator.\n\nIf you find yourself designing how ONE task dispatches safely rather than how\nMANY tasks are scheduled + reconciled, stop — that is the build-dispatch\nplaybook.\n\n## What you emit\n\n**No journey artifact.** This is a pure-orchestration playbook: the observable\nresult of the build — each task's **change-set** (files touched, attributed,\nsummarized) and **status** — is materialized by the runner on the dispatched\ntask rows (the build-dispatch playbook's mechanism), not authored here. A\nseparate schedule / wave-log artifact family is deliberately not added: the task\nrows already *are* the dispatch record and a second home for the same record\nwould drift (a typed wave-schedule / run-ledger contract is a filed later-phase\nitem). The creator authorizes the scale run (`approve_before`) before it fans\nout, and reviews the recorded change-sets + verify outcomes after — wave by\nwave, until the build plan is fully dispatched.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state,\n scope, and budget; confirm the build plan is approved and the foundation ran,\n and read every task's dispatch state to compute the frontier.\n- `.claude/skills/journey-approve/SKILL.md` — relay the exact pre-fan-out Authority Request\n gate decision that authorizes the workspace-mutating fan-out (never\n self-approve).\n- `.claude/skills/journey-run/SKILL.md` — trigger a scheduled wave; each coding\n slot invokes the single-flight dispatch contract and each deterministic\n generation step runs its companion endpoint.\n- `.claude/skills/journey-report/SKILL.md` — summarize a stretch of the build:\n which waves ran, which change-sets landed, what verify said, and any failed\n task left flagged for triage.\n\n## Reviewer checklist — `scale-schedule-sound`\n\nFormerly authored as an `llm_judge` quality gate; the generic rubric-only gate kind was retired at the flexible-intelligence hard cut (judgment now runs only through a compiled Evaluation Treatment). The checklist itself is creator-facing review guidance and is kept here, verbatim, minus the retired runner's closing sentence:\n\nJudge whether the SCALE orchestration ran the build soundly — the trust-but-verify reviewer pass over how MANY tasks were scheduled, parallelised, and reconciled, WITHOUT straying into how ONE task dispatches (that is the build-dispatch playbook's rubric) or how the plan was decomposed (the build-decompose playbook's). Assess six invariants and mark each PASS / CONCERN / GAP with a one-line evidence note. (1) WAVE READINESS — every task dispatched in a wave had ALL its prose prerequisites already SUCCEEDED (dispatched-and-verified), not merely attempted; a task dispatched while a prerequisite was un-run, in-flight, or dispatched-and-FAILED is a GAP (the build stage ran against a missing prerequisite). A prerequisite whose run FAILED (its change-set flagged under keep_and_flag) does NOT satisfy the dependency — its dependents must stay blocked, and dispatching them anyway is a GAP. (2) PARALLELISM SAFETY / ATTRIBUTION — the concurrent coding runs in a wave were isolated so each run's change-set is cleanly attributable (files RUN_EXCLUSIVE / APPEARED_DURING_RUN per run), via git worktree-per-agent isolation OR a module/resource partition that puts every concurrent agent on a DISJOINT file set. Two concurrent coding agents mutating the SAME worktree — which makes every touched file BASELINE_DIRTY_AMBIGUOUS and destroys per-run attribution — is a GAP (the single-flight floor was bypassed without an isolation answer). Note the honest floor: the runner enforces single-flight today, so on the current runner a 'wave' degrades to SEQUENTIAL single-flight dispatch and this invariant reads whether the METHOD declared a sound isolation model, not whether concurrency actually ran. (3) COMPANION-GENERATION INTERLEAVE — the deterministic companion-owned generation steps (labels / i18n, email templates, seeds) ran through their deterministic companion endpoints AFTER the resources / modules whose output they consume existed, at the right point in the schedule order; a generation step ordered before its inputs exist, or a missing generation step for authored surfaces, is a CONCERN; treating a deterministic generation step as a coding-agent dispatch (dispatching an agent for it) is a CONCERN. Note the honest floor: the generation steps do NOT take the coding single-flight lock, but the coding change-set capture is a whole-worktree time-window diff, so a generation step writing files WHILE a coding dispatch is capturing is misattributed to that coding run — so on today's runner the generation steps also serialize outside an active coding-capture window, and this invariant reads whether they ran at the right point in the ORDER, not whether they truly overlapped a coding run (safe overlap needs worktree isolation). (4) WAVE-COMPLETION RECONCILIATION — the next wave opened only after every task in the current frontier reached a terminal SUCCEEDED outcome (or was explicitly held as a blocked / flagged failure); advancing the schedule while a wave's tasks were still in-flight or with an unreconciled failure is a GAP (a downstream task could build on an unfinished prerequisite). (5) FAILURE DISPOSITION ACROSS SIBLINGS + DOWNSTREAM — a failed / timed-out task in a wave kept its captured change-set flagged for human triage (keep_and_flag), its already-dispatched siblings in the same wave were left to complete, and its DEPENDENTS in later waves stayed blocked until it was triaged and re-dispatched successfully; a failed task whose dependents were dispatched anyway, or a failure silently reverted / left un-recorded, is a GAP (F-5 workspace-safety violation). (6) BOUNDARY DISCIPLINE — the orchestration stays at SCALE depth: it derives ready-sets, schedules waves, sets the parallelism + isolation model, interleaves the companion-generation steps, and reconciles completion. It does NOT re-decompose the plan (the build-decompose playbook owns the task graph), does NOT re-specify the per-task dispatch mechanics (single-flight lock / context-pack / change-set capture / verify — the build-dispatch playbook owns those; the scale orchestrator INVOKES that contract per slot), and does NOT itself author schemas / fields / code (the coding agents do that at dispatch time). Evidence of re-decomposition, re-authoring the single-task dispatch contract, or the orchestrator authoring code itself is a CONCERN (scope creep out of the scale lane). (The checklist is declarative: nothing executes it; the deterministic gates and the creator's approval remain the floors.)\n",
|
|
24
27
|
"skillRefs": [
|
|
25
28
|
"journey-status",
|
|
26
29
|
"journey-approve",
|
|
27
30
|
"journey-run",
|
|
28
31
|
"journey-report"
|
|
29
|
-
]
|
|
30
|
-
"contextSources": [],
|
|
31
|
-
"suspendsForClarification": false,
|
|
32
|
-
"briefAdequacyGate": false,
|
|
33
|
-
"briefAdequacyExcludedSources": []
|
|
32
|
+
]
|
|
34
33
|
},
|
|
35
|
-
"executor": "
|
|
34
|
+
"executor": "composite",
|
|
35
|
+
"qualityGates": [
|
|
36
|
+
{
|
|
37
|
+
"ref": "scale-typecheck",
|
|
38
|
+
"kind": "deterministic_validator",
|
|
39
|
+
"validatorRef": "typecheck",
|
|
40
|
+
"required": true
|
|
41
|
+
}
|
|
42
|
+
],
|
|
36
43
|
"approval": "approve_before",
|
|
37
44
|
"budget": {
|
|
38
45
|
"maxRuns": 30
|
|
@@ -81,6 +81,10 @@ anything:
|
|
|
81
81
|
which modules are MVP-critical vs later) and the **VisionSnapshot**
|
|
82
82
|
(`vision-brief` — the product framing and differentiation).
|
|
83
83
|
|
|
84
|
+
// TODO CLI COMMAND: wildo context journey-status
|
|
85
|
+
// (read current journey scope + approved artifacts + any existing domain plan)
|
|
86
|
+
// TODO CLI COMMAND: wildo context requirements
|
|
87
|
+
// (read the functional / non-functional requirements to decompose)
|
|
84
88
|
|
|
85
89
|
You **read** `requirements` + `market-snapshot` + `feature-drafts` + `roadmap` +
|
|
86
90
|
`vision-brief`; you **write** the `domain-plan` families.
|
|
@@ -7,6 +7,10 @@
|
|
|
7
7
|
"model_domain_graph"
|
|
8
8
|
],
|
|
9
9
|
"preconditions": [
|
|
10
|
+
{
|
|
11
|
+
"kind": "phase_is",
|
|
12
|
+
"phase": "bottom_up"
|
|
13
|
+
},
|
|
10
14
|
{
|
|
11
15
|
"kind": "artifact_exists",
|
|
12
16
|
"selector": {
|
|
@@ -42,12 +46,12 @@
|
|
|
42
46
|
{
|
|
43
47
|
"family": "domain-plan",
|
|
44
48
|
"schemaRef": "saas-specifications:DomainPlanOutputSet",
|
|
49
|
+
"placement": "specifications/src/domain-plan/",
|
|
45
50
|
"description": "THE atomic domain plan: the module decomposition AND the inter-resource relationship drafts, one value, one landed file. (The former separate relationship-drafts family was collapsed into this output 2026-08-24 — the two were never independently meaningful, and the deterministic validator crosses them.) A working edit until a human commits it."
|
|
46
51
|
}
|
|
47
52
|
],
|
|
48
|
-
"stepOutputs": [],
|
|
49
53
|
"method": {
|
|
50
|
-
"guidance": "# Domain Plan — Definition Set → Modules + Resources + Relationships (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut meant to be\n> iterated. The decomposition heuristic, the resource-inventory convention, and\n> the relationship-intent shape below are deliberately explicit so they can be\n> tuned against real runs — treat them as a starting rubric, not a frozen\n> contract. The *analytical depth* of domain modelling (a full ERD, a\n> cardinality-to-FK solver and full domain-graph validation) is intentionally\n> shallow here and is deepened in a later phase; do\n> not perfect it in this playbook.\n\n## Where you are in the journey\n\nThis is the **first bottom-up playbook** — the pivot from **product definition**\n(top-down: vision, market, requirements, roadmap, business model) to **project\ndefinition** (bottom-up: the app's modules, resources, and how they relate). It\nruns **only after** the exact\n`top_down-to-bottom_up.bootstrap-non-regulated@0.1.0` route has produced a\ndurable `top_down → bottom_up` transition-commit fact. That fact proves the\nroute-bound readiness, semantic decision, Authority Request/Decision and phase\neffect chain; it is not an arbitrary approval flag. The separate\n`phase_is bottom_up` predicate checks the current phase projection. You are not\nre-opening product questions here — you are turning the currently accepted\nproduct definition into the *shape of the software that delivers it*.\n\n## What this playbook does\n\nYou are the **domain architect**. This playbook reads the approved definition set\nand drafts the **domain plan**: the answer to *\"what modules does this app have,\nwhat resources live in each, and how do those resources relate?\"* You produce\n**two artifacts**:\n\n1. The **domain-plan** family — the **module decomposition** with a **per-module\n resource inventory**, authored as a collection of **ModuleBusinessSemantics\n drafts** (one per proposed module). Each module draft states its purpose, its\n business capability, its primary actors, and its resource inventory\n (`mainResources` — the semantic center of the module; `supportingResources` —\n resources that support without being the center). The resource inventory lives\n **inside** each module draft because an inventory is inherently *per module*.\n2. The **relationship drafts** — carried INSIDE the same domain-plan value — the **inter-resource relationship\n intents**: for each durable association between two inventoried resources, the\n two ends, the **cardinality intent** (one-to-one / one-to-many / many-to-many),\n and the **ownership direction** (which resource holds the reference). These are\n typed conceptual drafts — a relationship is not a module, so it earns its own\n family, and the build loop consumes it when it wires FK fields.\n\nThis is a **planning pass**. You name modules, the resources inside them, and how\nthey relate. You do **not** author schemas, resolve a cardinality intent into a\nconcrete foreign-key field, or generate any code — that is the **bottom-up build\nloop's** job, downstream of this plan.\n\n## Read state first — the definition set you read, the two artifacts you write\n\nThis playbook is **idempotent** and, on a re-run, a *refinement*. Before drafting\nanything:\n\n1. Read the current journey state and scope through the `journey-status` skill (it\n owns the read; do not re-derive it here). Confirm the top-down set is present\n and approved, and check whether a `domain-plan` already\n exist from an earlier run (refine them, do not re-author — see below).\n2. Read the approved definition set. **Load-bearing** (these drive the\n decomposition): the **requirements** (`requirements` family — the functional and\n non-functional requirements the domain must satisfy), the capability-mapped\n **MarketSnapshot** (`market-snapshot` — the benefits wired to their delivering\n features, so you know what capability each feature carries), and the\n **feature-drafts** (the prose capability contracts — what each delivering\n feature actually is). **Contextual** (they shape emphasis, not the core\n decomposition): the **roadmap** (`roadmap` — the release phasing, so you can see\n which modules are MVP-critical vs later) and the **VisionSnapshot**\n (`vision-brief` — the product framing and differentiation).\n\n\nYou **read** `requirements` + `market-snapshot` + `feature-drafts` + `roadmap` +\n`vision-brief`; you **write** the `domain-plan` families.\n\n## Step 1 — Derive the modules (the decomposition)\n\nA **module** is a bounded slice of the app that delivers a coherent business\ncapability. Derive modules by **clustering** the definition set, not by guessing:\n\n1. **Cluster requirements and features by capability.** Group the functional\n requirements and the feature-drafts that serve one coherent capability (e.g.\n \"everything about authoring and tracking tasks\", \"everything about billing and\n plans\"). Each tight cluster is a candidate module. A feature-draft and the\n requirements it realises usually land in the same module.\n2. **Name each module and state its semantics.** For each candidate module author a\n `ModuleBusinessSemantics` draft: a `relatedModuleId` (the id the module registry\n will use — it must be **distinct across all module drafts**; two modules sharing\n an id silently collide, since the registry addresses modules by id), a `purpose`\n (why the module exists, in plain language), a\n `businessCapability` (the capability it delivers), the `primaryActors` (the\n human/business actors that interact with it), and — optionally — a\n `businessDomain` (the larger bounded-context label) and `integrationSurfaces`\n (named surfaces the module participates in).\n3. **Keep modules justified.** Every module must earn its existence from\n requirements or features in the definition set. Do **not** invent a module the\n definition set does not call for — a speculative module is a coherence CONCERN\n (see the quality gate). Conversely, if a requirement or feature has no home\n module, you are missing a module (a coverage GAP).\n\nThe `resource-add-module` skill carries the module-scaffolding vocabulary (what a\nmodule is across the project layout); read it to keep module boundaries idiomatic.\n\n## Step 2 — Inventory the resources per module\n\nFor each module, list the **resources** (persisted entity types) it owns. The\ninventory is **two lists on the module draft**:\n\n- **`mainResources`** — the resources that form the semantic **center** of the\n module (the entities the module is *about*: a `tasks` module's `task`).\n- **`supportingResources`** — resources that **support** the module's capability\n without being its center (lookup tables, join/junction entities, per-entity\n settings). A resource that is the center of the module belongs in `mainResources`,\n not here.\n\nRules for a plausible inventory:\n\n- **Derive resources from the requirements + feature-drafts**, not from a blank\n page: a requirement that says \"users can label tasks\" implies a `task` resource\n and (probably) a `label` resource. The `resource-add-resource` skill carries the\n vocabulary for what a resource is; read it to keep the inventory idiomatic.\n- **Each resource is inventoried in exactly one module** as its `mainResource`. A\n resource that is genuinely shared across modules is a signal you either have the\n module boundary wrong or you need a relationship (Step 3), not the same main\n resource duplicated in two modules.\n- **Do not author fields or schemas here.** The inventory names the resource and\n says which module owns it. What fields the resource carries, its enums, its\n decorators — all of that is the **build loop's** job. If you catch yourself\n writing a field list, stop: that is out of this playbook's depth.\n\n## Step 3 — Draft the inter-resource relationships\n\nOnce the resources are inventoried, capture how they **relate**. For each durable\nassociation between two inventoried resources, author a **relationship draft** in\nthe relationship drafts (inside the domain-plan value) stating:\n\n- **The two ends** — the two resources that relate (both must be inventoried in\n some module's inventory from Step 2; a relationship to an un-inventoried resource\n is a coverage GAP).\n- **The cardinality intent** — one-to-one, one-to-many, or many-to-many. This is an\n *intent*, in prose; you are not resolving it into a foreign-key placement here.\n- **The ownership direction** — which resource conceptually **holds** the reference\n (e.g. \"a `task` belongs to a `project`\" → the `task` end holds the reference).\n This is the *intent* the build loop needs; it does **not** decide the physical FK\n holder (that resolution — FK holder from cardinality, discriminator relationships,\n conditional relationships — is the `module-relationships` skill's job at build\n time, **not** here).\n\nThe `module-relationships` skill carries the technical HOW of realising a\nrelationship (FK fields, cardinality-to-FK-holder resolution, conditional /\ndiscriminator relationships). Read it to keep your relationship *intents* aligned\nwith what the build loop can actually wire — but do **not** perform that wiring in\nthis planning pass.\n\n## Refine, don't re-author\n\n- **Keep what still holds.** On a re-run, do not rename or re-decompose modules\n that are already correct. Only add a module, move a resource to a different\n module, or add/correct a relationship where the plan genuinely changed.\n- **Reuse existing module ids.** A module that already exists keeps its\n `relatedModuleId` — never mint a second id for the same module. Likewise, keep a\n resource's name stable across runs.\n- **Never orphan a relationship.** A relationship draft must name two resources\n that are actually inventoried in Step 2. If you move or rename a resource, follow\n it into every relationship draft that references it.\n\n## Executable semantic evaluation — `domain-plan-output-set-result`\n\nThe staged output set first passes deterministic structural validation: exact\nmodule/resource identities, typed relationship ends, unique ownership, and the\natomic manifest must all be valid. That is a non-bypassable eligibility floor,\nnot a semantic quality opinion.\n\nThe companion then executes the playbook's structured semantic Treatment over\nthe exact staged output-set artifact. Its six criteria remain distinct:\nrequirement coverage, feature coverage, module justification, inventory\nplausibility, relationship integrity, and planning-depth boundary discipline.\nEach criterion produces PASS / CONCERN / GAP / INDETERMINATE evidence, and the\nworst-verdict aggregation policy determines the Decision Rule consequence.\n\nA semantic PASS does **not** accept or publish the candidate. It transitions the\nresult Decision Point to `AUTHORITY_REQUIRED`; an explicit operator authority\ndecision is a separate later boundary. CONCERN or GAP requests revision,\nINDETERMINATE requests evidence, and evaluator or hard-floor failure blocks\nclosed. The evaluation path never mutates accepted specification heads.\n\n## Scaffold-depth boundary (deferred to a later depth phase)\n\nKeep this playbook at scaffold depth. Explicitly **out of scope here**:\n\n- **Schema / field authoring.** The inventory names resources and their owning\n module; it does **not** author fields, enums, decorators, or Zod schemas. That is\n the build loop. If you catch yourself writing a field list, stop.\n- **Cardinality-to-FK resolution.** A relationship draft states a cardinality\n *intent* and an ownership *intent* in prose. Resolving that into a physical\n foreign-key holder, a discriminator relationship, or a conditional relationship is\n the `module-relationships` skill's job **at build time**, not here.\n- **A full ERD / domain-graph solver.** Phases-of-a-graph, transitive dependency\n ordering, normalization analysis, and diagram generation are a later-phase\n concern. You draft modules, an inventory, and relationship intents — not a solved\n entity-relationship diagram.\n- **A full domain-graph solver.** The framework now ships a typed conceptual\n relationship-draft contract and deterministic structural validation for the\n atomic output set. It deliberately does not solve physical FK placement,\n normalization, graph execution order, discriminator relationships, or\n conditional relationships; those remain build-depth concerns.\n- **Code generation / module registration.** Scaffolding the module folders,\n registering the module across runtimes, generating resource files — all of that is\n the bottom-up build loop, downstream of this plan.\n\nIf you find yourself perfecting any of the above, stop and leave the slice at\nscaffold depth — depth is a dedicated later pass done once, holistically.\n\n## What you emit\n\nTwo artifacts for this journey:\n\n- The **domain-plan** under `specifications/src/domain-plan/` — a\n collection of `ModuleBusinessSemantics` drafts: the module decomposition, each\n module carrying its purpose, business capability, primary actors, and its\n `mainResources` / `supportingResources` inventory.\n- The **relationship drafts** inside the landed `specifications/src/domain-plan/` value\n — the inter-resource relationship intents (two ends + cardinality intent +\n ownership direction) between inventoried resources.\n\nAfter deterministic validation and semantic PASS, the runtime creates a distinct\nresult-bound Authority Request for the exact staged output-set digest. The local\noperator's explicit interface response settles that request; transition authority\ncannot substitute for it. Only then may the atomic specification-family mutation\naccept both files together for consumption by the bottom-up build loop.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state and\n scope, and confirm the approved top-down set is in place to plan the domain from.\n- `.claude/skills/resource-add-module/SKILL.md` — the module-scaffolding vocabulary\n (what a module is across the project layout); keeps module boundaries idiomatic.\n- `.claude/skills/resource-add-resource/SKILL.md` — the resource vocabulary (what a\n resource is); keeps the per-module inventory idiomatic.\n- `.claude/skills/module-relationships/SKILL.md` — the technical HOW of realising a\n relationship (FK fields, cardinality-to-FK-holder resolution, conditional /\n discriminator relationships) — consulted so relationship *intents* align with what\n the build loop can wire, NOT performed in this planning pass.\n",
|
|
54
|
+
"guidance": "# Domain Plan — Definition Set → Modules + Resources + Relationships (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut meant to be\n> iterated. The decomposition heuristic, the resource-inventory convention, and\n> the relationship-intent shape below are deliberately explicit so they can be\n> tuned against real runs — treat them as a starting rubric, not a frozen\n> contract. The *analytical depth* of domain modelling (a full ERD, a\n> cardinality-to-FK solver and full domain-graph validation) is intentionally\n> shallow here and is deepened in a later phase; do\n> not perfect it in this playbook.\n\n## Where you are in the journey\n\nThis is the **first bottom-up playbook** — the pivot from **product definition**\n(top-down: vision, market, requirements, roadmap, business model) to **project\ndefinition** (bottom-up: the app's modules, resources, and how they relate). It\nruns **only after** the exact\n`top_down-to-bottom_up.bootstrap-non-regulated@0.1.0` route has produced a\ndurable `top_down → bottom_up` transition-commit fact. That fact proves the\nroute-bound readiness, semantic decision, Authority Request/Decision and phase\neffect chain; it is not an arbitrary approval flag. The separate\n`phase_is bottom_up` predicate checks the current phase projection. You are not\nre-opening product questions here — you are turning the currently accepted\nproduct definition into the *shape of the software that delivers it*.\n\n## What this playbook does\n\nYou are the **domain architect**. This playbook reads the approved definition set\nand drafts the **domain plan**: the answer to *\"what modules does this app have,\nwhat resources live in each, and how do those resources relate?\"* You produce\n**two artifacts**:\n\n1. The **domain-plan** family — the **module decomposition** with a **per-module\n resource inventory**, authored as a collection of **ModuleBusinessSemantics\n drafts** (one per proposed module). Each module draft states its purpose, its\n business capability, its primary actors, and its resource inventory\n (`mainResources` — the semantic center of the module; `supportingResources` —\n resources that support without being the center). The resource inventory lives\n **inside** each module draft because an inventory is inherently *per module*.\n2. The **relationship drafts** — carried INSIDE the same domain-plan value — the **inter-resource relationship\n intents**: for each durable association between two inventoried resources, the\n two ends, the **cardinality intent** (one-to-one / one-to-many / many-to-many),\n and the **ownership direction** (which resource holds the reference). These are\n typed conceptual drafts — a relationship is not a module, so it earns its own\n family, and the build loop consumes it when it wires FK fields.\n\nThis is a **planning pass**. You name modules, the resources inside them, and how\nthey relate. You do **not** author schemas, resolve a cardinality intent into a\nconcrete foreign-key field, or generate any code — that is the **bottom-up build\nloop's** job, downstream of this plan.\n\n## Read state first — the definition set you read, the two artifacts you write\n\nThis playbook is **idempotent** and, on a re-run, a *refinement*. Before drafting\nanything:\n\n1. Read the current journey state and scope through the `journey-status` skill (it\n owns the read; do not re-derive it here). Confirm the top-down set is present\n and approved, and check whether a `domain-plan` already\n exist from an earlier run (refine them, do not re-author — see below).\n2. Read the approved definition set. **Load-bearing** (these drive the\n decomposition): the **requirements** (`requirements` family — the functional and\n non-functional requirements the domain must satisfy), the capability-mapped\n **MarketSnapshot** (`market-snapshot` — the benefits wired to their delivering\n features, so you know what capability each feature carries), and the\n **feature-drafts** (the prose capability contracts — what each delivering\n feature actually is). **Contextual** (they shape emphasis, not the core\n decomposition): the **roadmap** (`roadmap` — the release phasing, so you can see\n which modules are MVP-critical vs later) and the **VisionSnapshot**\n (`vision-brief` — the product framing and differentiation).\n\n// TODO CLI COMMAND: wildo context journey-status\n// (read current journey scope + approved artifacts + any existing domain plan)\n// TODO CLI COMMAND: wildo context requirements\n// (read the functional / non-functional requirements to decompose)\n\nYou **read** `requirements` + `market-snapshot` + `feature-drafts` + `roadmap` +\n`vision-brief`; you **write** the `domain-plan` families.\n\n## Step 1 — Derive the modules (the decomposition)\n\nA **module** is a bounded slice of the app that delivers a coherent business\ncapability. Derive modules by **clustering** the definition set, not by guessing:\n\n1. **Cluster requirements and features by capability.** Group the functional\n requirements and the feature-drafts that serve one coherent capability (e.g.\n \"everything about authoring and tracking tasks\", \"everything about billing and\n plans\"). Each tight cluster is a candidate module. A feature-draft and the\n requirements it realises usually land in the same module.\n2. **Name each module and state its semantics.** For each candidate module author a\n `ModuleBusinessSemantics` draft: a `relatedModuleId` (the id the module registry\n will use — it must be **distinct across all module drafts**; two modules sharing\n an id silently collide, since the registry addresses modules by id), a `purpose`\n (why the module exists, in plain language), a\n `businessCapability` (the capability it delivers), the `primaryActors` (the\n human/business actors that interact with it), and — optionally — a\n `businessDomain` (the larger bounded-context label) and `integrationSurfaces`\n (named surfaces the module participates in).\n3. **Keep modules justified.** Every module must earn its existence from\n requirements or features in the definition set. Do **not** invent a module the\n definition set does not call for — a speculative module is a coherence CONCERN\n (see the quality gate). Conversely, if a requirement or feature has no home\n module, you are missing a module (a coverage GAP).\n\nThe `resource-add-module` skill carries the module-scaffolding vocabulary (what a\nmodule is across the project layout); read it to keep module boundaries idiomatic.\n\n## Step 2 — Inventory the resources per module\n\nFor each module, list the **resources** (persisted entity types) it owns. The\ninventory is **two lists on the module draft**:\n\n- **`mainResources`** — the resources that form the semantic **center** of the\n module (the entities the module is *about*: a `tasks` module's `task`).\n- **`supportingResources`** — resources that **support** the module's capability\n without being its center (lookup tables, join/junction entities, per-entity\n settings). A resource that is the center of the module belongs in `mainResources`,\n not here.\n\nRules for a plausible inventory:\n\n- **Derive resources from the requirements + feature-drafts**, not from a blank\n page: a requirement that says \"users can label tasks\" implies a `task` resource\n and (probably) a `label` resource. The `resource-add-resource` skill carries the\n vocabulary for what a resource is; read it to keep the inventory idiomatic.\n- **Each resource is inventoried in exactly one module** as its `mainResource`. A\n resource that is genuinely shared across modules is a signal you either have the\n module boundary wrong or you need a relationship (Step 3), not the same main\n resource duplicated in two modules.\n- **Do not author fields or schemas here.** The inventory names the resource and\n says which module owns it. What fields the resource carries, its enums, its\n decorators — all of that is the **build loop's** job. If you catch yourself\n writing a field list, stop: that is out of this playbook's depth.\n\n## Step 3 — Draft the inter-resource relationships\n\nOnce the resources are inventoried, capture how they **relate**. For each durable\nassociation between two inventoried resources, author a **relationship draft** in\nthe relationship drafts (inside the domain-plan value) stating:\n\n- **The two ends** — the two resources that relate (both must be inventoried in\n some module's inventory from Step 2; a relationship to an un-inventoried resource\n is a coverage GAP).\n- **The cardinality intent** — one-to-one, one-to-many, or many-to-many. This is an\n *intent*, in prose; you are not resolving it into a foreign-key placement here.\n- **The ownership direction** — which resource conceptually **holds** the reference\n (e.g. \"a `task` belongs to a `project`\" → the `task` end holds the reference).\n This is the *intent* the build loop needs; it does **not** decide the physical FK\n holder (that resolution — FK holder from cardinality, discriminator relationships,\n conditional relationships — is the `module-relationships` skill's job at build\n time, **not** here).\n\nThe `module-relationships` skill carries the technical HOW of realising a\nrelationship (FK fields, cardinality-to-FK-holder resolution, conditional /\ndiscriminator relationships). Read it to keep your relationship *intents* aligned\nwith what the build loop can actually wire — but do **not** perform that wiring in\nthis planning pass.\n\n## Refine, don't re-author\n\n- **Keep what still holds.** On a re-run, do not rename or re-decompose modules\n that are already correct. Only add a module, move a resource to a different\n module, or add/correct a relationship where the plan genuinely changed.\n- **Reuse existing module ids.** A module that already exists keeps its\n `relatedModuleId` — never mint a second id for the same module. Likewise, keep a\n resource's name stable across runs.\n- **Never orphan a relationship.** A relationship draft must name two resources\n that are actually inventoried in Step 2. If you move or rename a resource, follow\n it into every relationship draft that references it.\n\n## Executable semantic evaluation — `domain-plan-output-set-result`\n\nThe staged output set first passes deterministic structural validation: exact\nmodule/resource identities, typed relationship ends, unique ownership, and the\natomic manifest must all be valid. That is a non-bypassable eligibility floor,\nnot a semantic quality opinion.\n\nThe companion then executes the playbook's structured semantic Treatment over\nthe exact staged output-set artifact. Its six criteria remain distinct:\nrequirement coverage, feature coverage, module justification, inventory\nplausibility, relationship integrity, and planning-depth boundary discipline.\nEach criterion produces PASS / CONCERN / GAP / INDETERMINATE evidence, and the\nworst-verdict aggregation policy determines the Decision Rule consequence.\n\nA semantic PASS does **not** accept or publish the candidate. It transitions the\nresult Decision Point to `AUTHORITY_REQUIRED`; an explicit operator authority\ndecision is a separate later boundary. CONCERN or GAP requests revision,\nINDETERMINATE requests evidence, and evaluator or hard-floor failure blocks\nclosed. The evaluation path never mutates accepted specification heads.\n\n## Scaffold-depth boundary (deferred to a later depth phase)\n\nKeep this playbook at scaffold depth. Explicitly **out of scope here**:\n\n- **Schema / field authoring.** The inventory names resources and their owning\n module; it does **not** author fields, enums, decorators, or Zod schemas. That is\n the build loop. If you catch yourself writing a field list, stop.\n- **Cardinality-to-FK resolution.** A relationship draft states a cardinality\n *intent* and an ownership *intent* in prose. Resolving that into a physical\n foreign-key holder, a discriminator relationship, or a conditional relationship is\n the `module-relationships` skill's job **at build time**, not here.\n- **A full ERD / domain-graph solver.** Phases-of-a-graph, transitive dependency\n ordering, normalization analysis, and diagram generation are a later-phase\n concern. You draft modules, an inventory, and relationship intents — not a solved\n entity-relationship diagram.\n- **A full domain-graph solver.** The framework now ships a typed conceptual\n relationship-draft contract and deterministic structural validation for the\n atomic output set. It deliberately does not solve physical FK placement,\n normalization, graph execution order, discriminator relationships, or\n conditional relationships; those remain build-depth concerns.\n- **Code generation / module registration.** Scaffolding the module folders,\n registering the module across runtimes, generating resource files — all of that is\n the bottom-up build loop, downstream of this plan.\n\nIf you find yourself perfecting any of the above, stop and leave the slice at\nscaffold depth — depth is a dedicated later pass done once, holistically.\n\n## What you emit\n\nTwo artifacts for this journey:\n\n- The **domain-plan** under `specifications/src/domain-plan/` — a\n collection of `ModuleBusinessSemantics` drafts: the module decomposition, each\n module carrying its purpose, business capability, primary actors, and its\n `mainResources` / `supportingResources` inventory.\n- The **relationship drafts** inside the landed `specifications/src/domain-plan/` value\n — the inter-resource relationship intents (two ends + cardinality intent +\n ownership direction) between inventoried resources.\n\nAfter deterministic validation and semantic PASS, the runtime creates a distinct\nresult-bound Authority Request for the exact staged output-set digest. The local\noperator's explicit interface response settles that request; transition authority\ncannot substitute for it. Only then may the atomic specification-family mutation\naccept both files together for consumption by the bottom-up build loop.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state and\n scope, and confirm the approved top-down set is in place to plan the domain from.\n- `.claude/skills/resource-add-module/SKILL.md` — the module-scaffolding vocabulary\n (what a module is across the project layout); keeps module boundaries idiomatic.\n- `.claude/skills/resource-add-resource/SKILL.md` — the resource vocabulary (what a\n resource is); keeps the per-module inventory idiomatic.\n- `.claude/skills/module-relationships/SKILL.md` — the technical HOW of realising a\n relationship (FK fields, cardinality-to-FK-holder resolution, conditional /\n discriminator relationships) — consulted so relationship *intents* align with what\n the build loop can wire, NOT performed in this planning pass.\n",
|
|
51
55
|
"skillRefs": [
|
|
52
56
|
"journey-status",
|
|
53
57
|
"resource-add-module",
|
|
@@ -66,13 +70,10 @@
|
|
|
66
70
|
]
|
|
67
71
|
}
|
|
68
72
|
]
|
|
69
|
-
}
|
|
70
|
-
"contextSources": [],
|
|
71
|
-
"suspendsForClarification": true,
|
|
72
|
-
"briefAdequacyGate": false,
|
|
73
|
-
"briefAdequacyExcludedSources": []
|
|
73
|
+
}
|
|
74
74
|
},
|
|
75
75
|
"executor": "companion_agent",
|
|
76
|
+
"qualityGates": [],
|
|
76
77
|
"approval": "approve_result",
|
|
77
78
|
"budget": {
|
|
78
79
|
"maxRuns": 3
|