Home / Engine / Craft Knowledge

Craft Knowledge Engine - Phase 3 spec: the nightly craft grower (v1, 2026-06-20)

Updated Jun 20, 2026 · Affirmology_CraftEngine_Phase3_GrowthSpec_v1.md

Craft Knowledge Engine - Phase 3 spec: the nightly craft grower (v1, 2026-06-20)

Phases 1 and 2 are done: the craft base exists (94 entries) and is wired into the council (Hypnos plans the techniques, Orpheus drafts with the plan, Apollo gates on it, Hermes search_craft in chat). Phase 3 makes the craft base GROW on its own each night, the same way the Interpretation Growth Engine already grows the chart-meaning layer. Jeff: "look wide and far, be smart."

The good news: no new infrastructure

The nightly job already exists and already does exactly the plumbing we need. api/growth_cron.py runs as a Render Cron, pulls corpus.db from R2, runs affirmology.corpus.growth.run_growth(...), and pushes the enriched corpus.db back to R2. The studio re-pulls on next boot, so the new knowledge reaches the agents. The craft table lives in that SAME corpus.db. So Phase 3 is: add a craft-growing STAGE to run_growth, and the existing pull/push/report pipeline carries it for free.

What the existing engine does (so Phase 3 mirrors it)

affirmology/corpus/growth.py runs three stages over the meaning store, all cost-capped by a Budget (hard USD cap + per-run entry cap), all idempotent (upsert, never duplicate), pilot-before-batch (verify one entry before spending on the batch), cheapest good model (Haiku) by default: 1. MEANING BUILDER: walks a prioritized target list (wealth first), grounds each on the raw corpus, writes a craft-voiced meaning entry, upserts it. 2. FEEDBACK / CORRECTIONS: turns every "this reads odd" from the studio feedback store into a permanent distinction + fix-flag. 3. MORNING REPORT: what was added/refined/corrected + the budget ledger, printed to stdout and pushed to R2 (reports/growth_latest.md).

Phase 3 adds a fourth and fifth stage of the same shape, writing to the craft store instead of the meaning store.

What to build

Stage 4 - CRAFT BUILDER (grow the craft base)

A new function build_craft(...) in growth.py, mirroring build_meaning, that walks a prioritized craft backlog and upserts actionable craft entries (the Phase 1 schema: area, name, method, why, when_to_use, how_to_apply, one_liner, body, tags, confidence, source, source_doc).

• TARGETS: a default_craft_targets() returning (area, topic) pairs across the five areas, prioritized by what most improves an audio:
• technique (meditation/hypnosis): induction styles, the hypnagogic window, deepening, fractionation, suggestion phrasing, pacing and pauses, embedded commands, the openings and endings craft, letting a recognition land, parts integration, future-pacing.
• neuroscience: the predictive brain and prediction-error, identity-update through repetition, emotional salience and encoding, state-dependent memory, the suggestibility window before sleep, why first-person present tense rewrites faster.
• frequency: delta for deep sleep, theta for journey and reverie, alpha for relaxed receptivity, schumann grounding, solfeggio claims (state honestly what is evidenced vs traditional), isochronic vs binaural vs monaural, carrier tones, when NOT to use entrainment.
• audio_production: voice intimacy and proximity, the bed-to-voice ratio, loudness and dynamic range for a calm listen, reverb as sacred space, silence as an instrument, de-essing and warmth, headphone vs speaker masters.
• reading_craft: the Forrest standard extended (mechanism over keyword, high road / low road, pairing wound with gift, never deterministic, the developmental frame), how pro astrologers open, hold, and close a reading.
• GROUNDING (the "look wide" part): two tiers, build 3a now, 3b later.
• 3a (ship now, no browsing infra): the distiller writes each actionable entry from the model's own knowledge against a SPECIFIC topic prompt, tier-walled (see guardrails). Cheap, cloud-safe, fits the existing cron exactly. The backlog itself is the "wide" surface, and it expands over time (the report lists pending topics; we add to the backlog).
• 3b (upgrade, separate): a true wide-crawl grounding step - an allowlisted web research pass (neuroscience and audio-efficacy literature, meditation and hypnosis method, sound science, pro reading method) that grounds each entry in fetched sources before distillation. Gated by env so it is off until we wire a research source. This is where "crawl wide and far" becomes literal.
• IDEMPOTENT: upsert keyed on (area, name). Re-runs refine, never duplicate. Pilot-before-batch. Respects the same Budget.

Stage 5 - CRAFT FEEDBACK (close the loop)

Mirror process_feedback, but for craft. Two inputs become craft refinements: - APOLLO GATE failures from --council renders: when Apollo's technique/hypnos gate says a planned technique was misapplied or something that belonged was missing, that judgment is distilled into a craft correction (sharpen the entry's how_to_apply, or add a when_NOT_to_use). The council already produces this judgment in council_transcript.md; Stage 5 reads a small structured log of gate misses (have the council append gate-miss notes to a craft_feedback channel, same shape as the studio feedback store). - ECHO "didn't land": any audio feedback tagged craft ("the opening dragged", "the ending didn't release") becomes a craft distinction the writer and Hypnos must honor next time.

Wiring + report

• run_growth gains the two stages, gated by GROWTH_CRAFT=1 (default on in cloud, easy to toggle). Add caps GROWTH_CRAFT_MAX_ENTRIES (default 25) sharing the same USD Budget, so a single nightly cap covers both meaning and craft growth and we never overspend.
• morning_report gains a CRAFT section: entries added/refined, craft corrections learned, craft store total, pending topics.
• growth_cron.py needs NO change beyond passing through (it already calls run_growth and pushes the DB). Confirm the craft table is created by the seed step on first run.

Guardrails (hard)

• TIER-WALL: never ingest Tier C copyrighted text (Richard Rudd official Gene Keys, Ra Uru Hu / Jovian Archive) as craft content. Benchmark-only, never stored. The distiller writes ORIGINAL actionable method, not quotes.
• BRAND: no em dashes; never name the meditation teacher (say "heart coherence breath" / "embodied gratitude induction"); the craft voice is instructional-to-the-agent, not client copy.
• HONESTY on frequency: where a claim is traditional rather than evidenced (e.g. specific solfeggio healing numbers), the entry says so in why. We do not assert pseudoscience as fact.
• DEMO LOCKED: craft growth only affects the Studio --council path. The demo never passes --council and is untouched.
• COST: one hard USD cap for the whole nightly run (meaning + craft), per-run entry caps, pilot-before-batch, cheapest good model. Same discipline already proven in Phase B.

Sequence

• Build 3a now (Stage 4 craft builder + Stage 5 craft feedback + report + env gates). Small, mirrors code that already works, ships in the existing cron.
• 3b (wide web-crawl grounding) is a follow-up once we choose a research source; the env gate is already there for it.

Acceptance test

1. Run locally: GROWTH_CRAFT=1 GROWTH_MAX_COST_USD=0.50 GROWTH_CRAFT_MAX_ENTRIES=3 python -m api.growth_cron against a local corpus.db. PASS = 3 new/ refined craft entries, the morning report shows a CRAFT section with a budget under cap, and a re-run refines rather than duplicates (idempotent).
2. After the nightly cloud run, search_craft in Hermes and the Hypnos plan in a --council render surface the newly grown entries.

Build brief for Code (paste below)

See the chat message that delivered this spec for the exact Code paste and the run commands.