feat: add pour warning for vapor-phase formulas, improve help text, add doctor check

- Add Phase field to Formula type to indicate recommended instantiation phase
- Add warning in 'bd mol pour' when formula has phase="vapor"
- Improve pour/wisp help text with clear comparison of when to use each
- Add CheckPersistentMolIssues doctor check to detect mol- issues in JSONL
- Update beads-release.formula.json with phase="vapor"

This helps prevent accidental persistence of ephemeral workflow issues.
This commit is contained in:
Steve Yegge
2025-12-28 01:34:01 -08:00
parent b5ab4f2a3b
commit dfc796589f
7 changed files with 137 additions and 14 deletions

View File

@@ -21,20 +21,29 @@ var pourCmd = &cobra.Command{
Short: "Instantiate a proto as a persistent mol (solid -> liquid)",
Long: `Pour a proto into a persistent mol - like pouring molten metal into a mold.
This is the chemistry-inspired command for creating persistent work from templates.
This is the chemistry-inspired command for creating PERSISTENT work from templates.
The resulting mol lives in .beads/ (permanent storage) and is synced with git.
Phase transition: Proto (solid) -> pour -> Mol (liquid)
Use pour for:
- Feature work that spans sessions
- Important work needing audit trail
- Anything you might need to reference later
WHEN TO USE POUR vs WISP:
pour (liquid): Persistent work that needs audit trail
- Feature implementations spanning multiple sessions
- Work you may need to reference later
- Anything worth preserving in git history
wisp (vapor): Ephemeral work that auto-cleans up
- Release workflows (one-time execution)
- Patrol cycles (deacon, witness, refinery)
- Health checks and diagnostics
- Any operational workflow without audit value
TIP: Formulas can specify phase:"vapor" to recommend wisp usage.
If you pour a vapor-phase formula, you'll get a warning.
Examples:
bd mol pour mol-feature --var name=auth # Create persistent mol from proto
bd mol pour mol-release --var version=1.0 # Release workflow
bd mol pour mol-review --var pr=123 # Code review workflow`,
bd mol pour mol-feature --var name=auth # Persistent feature work
bd mol pour mol-review --var pr=123 # Persistent code review`,
Args: cobra.ExactArgs(1),
Run: runPour,
}
@@ -85,6 +94,18 @@ func runPour(cmd *cobra.Command, args []string) {
subgraph = sg
protoID = sg.Root.ID
isFormula = true
// Warn if formula recommends vapor phase (bd-mol cleanup)
if sg.Phase == "vapor" {
fmt.Fprintf(os.Stderr, "%s Formula %q recommends vapor phase (ephemeral)\n", ui.RenderWarn("⚠"), args[0])
fmt.Fprintf(os.Stderr, " Consider using: bd mol wisp %s", args[0])
for _, v := range varFlags {
fmt.Fprintf(os.Stderr, " --var %s", v)
}
fmt.Fprintf(os.Stderr, "\n")
fmt.Fprintf(os.Stderr, " Pour creates persistent issues that sync to git.\n")
fmt.Fprintf(os.Stderr, " Wisp creates ephemeral issues that auto-cleanup.\n\n")
}
}
if subgraph == nil {