{"record":{"id":"048dceed64b751a1","repo":"gastownhall/beads","slug":"waits-for-children-of-requires-a-step-id","errorCode":null,"errorMessage":"waits_for children-of() requires a step ID","messagePattern":"waits_for children-of\\(\\) requires a step ID","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/formula/types.go","lineNumber":760,"sourceCode":"\treturn nil\n}\n\n// validateWaitsFor validates the waits_for field value.\n// Valid formats:\n//   - \"all-children\": wait for all dynamically-bonded children\n//   - \"any-children\": wait for first child to complete\n//   - \"children-of(step-id)\": wait for children of a specific step\nfunc validateWaitsFor(value string, stepIDLocations map[string]string) error {\n\t// Simple gate types\n\tif value == \"all-children\" || value == \"any-children\" {\n\t\treturn nil\n\t}\n\n\t// children-of(step-id) syntax\n\tif strings.HasPrefix(value, \"children-of(\") && strings.HasSuffix(value, \")\") {\n\t\tstepID := value[len(\"children-of(\") : len(value)-1]\n\t\tif stepID == \"\" {\n\t\t\treturn fmt.Errorf(\"waits_for children-of() requires a step ID\")\n\t\t}\n\t\tif _, exists := stepIDLocations[stepID]; !exists {\n\t\t\treturn fmt.Errorf(\"waits_for references unknown step %q in children-of()\", stepID)\n\t\t}\n\t\treturn nil\n\t}\n\n\treturn fmt.Errorf(\"waits_for has invalid value %q (must be all-children, any-children, or children-of(step-id))\", value)\n}\n\n// validateChildDependsOn recursively validates depends_on and needs references for children.\nfunc validateChildDependsOn(children []*Step, idLocations map[string]string, errs *[]string, prefix string) {\n\tfor i, child := range children {\n\t\tchildPrefix := fmt.Sprintf(\"%s.children[%d]\", prefix, i)\n\t\tfor _, dep := range child.DependsOn {\n\t\t\tif _, exists := idLocations[dep]; !exists {\n\t\t\t\t*errs = append(*errs, fmt.Sprintf(\"%s (%s): depends_on references unknown step %q\", childPrefix, child.ID, dep))\n\t\t\t}","sourceCodeStart":742,"sourceCodeEnd":778,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/formula/types.go#L742-L778","documentation":"Formula validation supports waits_for values of the form children-of(step-id). This error is returned when the children-of(...) parentheses are empty — the syntax is recognized but no step ID was supplied, so the dependency is meaningless.","triggerScenarios":"A step's waits_for field contains exactly \"children-of()\" (or \"children-of( )\") — the value passes the prefix/suffix check but the extracted stepID is empty.","commonSituations":"Authoring a formula and forgetting to fill in the step ID placeholder, or programmatic generation emitting an empty dependency list item.","solutions":["Put the target step ID inside the parentheses: waits_for = \"children-of(setup)\".","If no dependency is needed, remove the waits_for entry entirely.","Verify the referenced step ID exists elsewhere in the formula (otherwise the next check reports an unknown step)."],"exampleFix":"// before\nwaits_for = \"children-of()\"\n// after\nwaits_for = \"children-of(build)\"","handlingStrategy":"validation","validationCode":"for _, w := range step.WaitsFor {\n    if strings.HasPrefix(w, \"children-of(\") && strings.TrimSuffix(strings.TrimPrefix(w, \"children-of(\"), \")\") == \"\" {\n        return fmt.Errorf(\"step %s: empty children-of() dependency\", step.ID)\n    }\n}","typeGuard":null,"tryCatchPattern":"if verr := f.Validate(); verr != nil && strings.Contains(verr.Error(), \"children-of() requires a step ID\") { /* fix the waits_for entry */ }","preventionTips":["Never emit children-of() without an explicit step ID.","Validate waits_for entries whenever a formula is authored or edited.","Prefer a plain step ID when depending on a single step; reserve children-of for grouped children."],"tags":["formula","validation","dependencies"],"backgroundTag":"invalid-dependency-reference","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}