# Process Spine — A and B The ordered procedure. Each step names its **inputs**, its **KG reads**, the **laws** it must satisfy (by id — text is in `laws.md` / `provenance.md`), its **output artifact**, and its **gate**. This file states no law and no number; it is the sequence only. Both operations run as **isolated steps** — each step's inputs are explicit (prior artifacts on disk + KG reads); nothing is assumed to carry over in conversation. That isolation is what forces every guardrail to be externalised into these files rather than living in a prompt's memory. The two human gates are **hard stops**: the sequence gate ends A, the compile gate ends B. --- ## Operation A — Chapter Research + Sequence **Input:** a chapter id (`GC`) + the target in `lever:content_scope`. ### A0 · Resolve + preflight Resolve the chapter's textbook in the KG: `kg_list_source_docs(curriculum, grade)` → pick the book → `kg_get_source_outline(doc_id)` → the chapter's page range. - Laws: `R-CHP-01`. If the book is absent → `gap::kg_source_absent`, stop and report (`R-GND-02/03`). ### A1 · Extract the chapter `kg_get_source_pages(doc_id, page_start, page_end)` (+ `kg_search_sources` for specifics). Build the structured `textbook_extract`: sections (id, title, pages, key objects, cognitive register, exercise density, any textbook-flagged misconceptions), vocabulary, notation, cultural anchors, CPA trajectory, teach-time estimate — **and the textbook's own `worked_examples[]` and `exemplar_questions[]` (the "Figure it Out" / exercise prompts) captured verbatim, each with its `kg_source::::p` cite** (these feed `R-CHP-14` assignment and `R-BLU-23` use). - Laws: `R-CHP-01`, `R-CHP-06`; every extracted claim cites `kg_source::::p` (`R-GND-05`). - Output: `textbook_extract.json`. ### A2 · KG evidence assembly (deterministic, zero-LLM) Scope the KG for the chapter and FK-expand from surfaced LOs. One battery of reads, bounded by `lever:kg_retrieval`: `kg_list_los`(grade+strand) → surfaced LOs → **FK-expand** each to its `misconception_ids`, `false_friend_ids`, `insight_record_ids`, `prerequisite_lo_codes` via `kg_lo_neighborhood` / `kg_list_ai_tags`; plus `kg_list_misconceptions`, ported `visual_insight_records` + `interactive_landscape` + `false_friends` (now KG-tagged), `kg_list_ias_patterns`, `kg_list_convention_differences`, learning-progression edges, `lo_components` (component reuse universe), curriculum + bridge nodes. - **Extracted-asset reuse universe** (per `R-GND-04`): for each surfaced LO, also pull the KG's *already-built* assets — `kg_list_ai_tags` (which lesson slides / images / applets / mcp-sims / videos teach this LO, with evidence + confidence) and `kg_lesson_full` (the per-asset briefs). This is the reuse candidate set B4/B3 draw on. - Laws: tag every row `kg_node::…::` (`R-GND-05`); `R-GND-01` (real nodes only); `R-GND-04` (record the reuse candidates). - Output: the evidence bundle (`_refs/kg_*.json`) + the **asset-reuse candidate index** (LO → existing assets by kind), each row provenance-tagged. ### A3 · Synthesise (LLM — the model's domain knowledge, guardrailed) The model **synthesises, connects, and gap-flags** over the pre-assembled evidence — it does not re-research. Produce the LO brief and the KG synthesis. - **`CHAPTER_LO_BRIEF`**: chapter LO + subgoals, prerequisite chain, ≥5-curriculum alignment, surfaced-LO universe (each with `relevance` + dual-ID + provenance). - Laws: `R-CHP-02`, `R-CHP-03`, `R-CHP-04`, `R-GND-01/04/05/06`; dual-ID per `provenance.md`. - **`CHAPTER_KG_SYNTHESIS`**: misconceptions (full payload), visual models, KG-resolved interactive URLs, IAS recommendations, vocabulary status, false-friends, conventions, tropes, gaps, cultural anchors. - Laws: `R-CHP-05`, `R-CHP-06`, `R-GND-01/02/03/05`; never-synthesize list for URLs/ids. - Output: `CHAPTER_LO_BRIEF.json`, `CHAPTER_KG_SYNTHESIS.json`. ### A4 · Sequence into journeys Decompose the chapter LO into the ordered `CHAPTER_JOURNEY_SEQUENCE`. **Journey count and boundaries are set by the time filter** — every journey sized to `lever:time.journey_budget_minutes` within `lever:time.journey_flex_band_minutes` (the 15–20 min unit), summed against the textbook estimate within `lever:sequence.textbook_time_tolerance_fraction` — together with the content drivers (section count, page span, exercise density). Each journey typed, CPA-phased, LO-bound, annotated, and assigned a `tgar_role` — TGAR cascades across the journey cluster, not necessarily within one journey (`R-CHP-18`); reconciliation map if existing journeys are present. - Laws: `R-CHP-07` (content-driven count + time budget)…`R-CHP-12` (the time budget is one of the three conjoined constraints), `R-CHP-14`, `R-CHP-15`, `R-CHP-17`, `R-CHP-18`; reuse-first components `R-GND-04`. - Output: `CHAPTER_JOURNEY_SEQUENCE.json`. ### A5 · Coverage close Build `COVERAGE` over every surfaced LO code; every code covered or explicitly acknowledged. - Laws: `R-CHP-16` (must reach 0 genuinely-uncovered). - Output: `COVERAGE.json`, `KB_HIERARCHY.json`. ### ▪ GATE A · Sequence approval (HARD STOP) Render the ordered journey list for the human. On approval, `R-CHP-13` **locks** `{position, journey_title, content_type, lo_codes, cpa_phase}` for every journey. Only then may Operation B run — one journey at a time. --- ## Operation B — Journey + Applet Blueprint **Input:** one **locked** journey record from `CHAPTER_JOURNEY_SEQUENCE` + the `CHAPTER_KG_SYNTHESIS`. (Re-read the KG for journey-scope narrowing as needed.) ### B0 · Load + narrow + gather reuse candidates Load the locked journey header (never mutate it — `R-CHP-13`) and the chapter synthesis. Narrow the KG evidence to this journey's LO, and **pull the asset-reuse candidate index** for it (`kg_list_ai_tags` / `kg_lesson_full` / neighbourhood on the journey LOs) — the existing screens / images / applets / mcp-sims / videos the KG has extracted for this LO (`R-GND-04`, `R-BLU-22`). This index feeds every authoring step below: **reuse or adapt before you author net-new**. ### B1 · Define the journey spine **The spine is the core-teaching backbone** — the ordered sequence of content screens that carries the concept from Activate to Consolidate: the CPA progression, the worked examples, the prerequisite and vocabulary screens. It is authored **first**, and targets `lever:time.spine_target_fraction` of the journey budget (the remaining headroom is enrichment — tropes-as-screen-pairs, applets, videos, media, placed in B3). Lay out the six sections and the spine screens; place the required semantic-tag tropes; assign CPA phases and the scaffolding arc. - **Reuse-first:** for each spine screen/image, check the reuse index — adopt an extracted KG screen/image where one teaches this beat (`R-BLU-22`), author new only on no-match. - **Textbook examples & questions:** populate the **Get** worked examples and the **Ask/Exit** questions from this journey's assigned `textbook_examples` / `exemplar_questions` (from A1), each page-cited; author new only to fill an uncovered beat (`R-BLU-23`). - Laws: `R-BLU-01`, `R-BLU-02`, `R-BLU-03`, `R-BLU-04`, `R-BLU-05`, `R-BLU-06`, `R-BLU-22`, `R-BLU-23`. - Primitives: `vocabulary.md §2, §3`. Budget: `lever:time.spine_target_fraction`, `lever:time.role_minutes_table`. ### B2 · Enrich per-screen Attach the per-screen fields (major idea, tgar role, visual-model description, transition, scaffolding level, vocabulary-on-screen) and the commitment tags. Materialise conventions/false-friends. - Laws: `R-BLU-07`, `R-BLU-13`, `R-BLU-14`, `R-BLU-16`, `R-BLU-17`. ### B3 · Place applets + videos Where `R-BLU-08` escalates or `R-BLU-10` licenses, insert the three-screen sandwich; classify screen roles. - Laws: `R-BLU-08`, `R-BLU-09`, `R-BLU-10`. Roles: `vocabulary.md §6`. Cap: `lever:blueprint.applets_per_journey_soft_cap`. ### B4 · Build each applet blueprint For every applet placeholder, author the six-stage screen sequence, construction-grade. - Laws: `R-BLU-11`, `R-BLU-12`, `R-BLU-18`, `R-BLU-19`, `R-BLU-20`, `R-BLU-21`. - Primitives: `vocabulary.md §4`. ### B5 · Compile (deterministic, zero-LLM) Run the compile pass: structural invariants + provenance completeness. Assign `asset_context_role` deterministically. Return every violation; **never** silently repair. - Enforces every `compile`-seam law above + `R-GND-05`. Pacing checked against `lever:time.role_minutes_table`. - Output: `{ok, violations[], stats}`. ### ▪ GATE B · Blueprint checkpoint (HARD STOP) Render the blueprint for the human. A non-empty `violations[]` means regenerate the offending artifact — **not** hand-patch around a violation. On approval the journey is construction-ready. --- ## Where the guardrails bite (summary) | Seam | What runs | Laws it carries | |---|---|---| | `kg` | reads resolve against real KG nodes; proposed nodes route to the KG authoring gate | `R-GND-01/04`, all "real-node" clauses | | `compile` | zero-LLM structural + provenance pass (A5, B5) | every `[HARD]` machine-checkable law | | `prompt` | guardrails instructed into A3/A4 and B1–B4 generation | every `[SOFT]` law + judgment-bearing `[HARD]` law | | human gate | sequence approval (A) and blueprint checkpoint (B) | locks (`R-CHP-13`); regenerate-not-patch discipline | The model's domain knowledge does the authoring in A3/A4 and B1–B4; the kit's job is only to keep that authoring **grounded** (`kg`), **structurally sound** (`compile`), and **house-consistent** (`prompt`), then hand a human the two decisions that matter (the sequence, the blueprint).