# ACRLDS Authoring Kit — Chapter Research (A) + Journey Blueprint (B), KG-native

**What this is.** A portable *guardrail kit* for the two generation operations:

- **Operation A — Chapter Research + Sequence.** Given a chapter, produce the chapter LO brief, the KG-grounded research synthesis, and the ordered chapter → journey sequence.
- **Operation B — Journey Blueprint.** Given one journey from that sequence, produce the construction-grade journey + applet blueprint.

**The stance (read this first).** The LLM already knows the domain — CPA, cognitive load, ZPD, scaffolding, curriculum theory. This kit does **not** re-teach any of that. It encodes only the *delta*: the house-specific delivery conventions and the research-backed invariants a competent model would not reliably produce on its own. The laws are **guardrails that make the best of the model's own domain knowledge** — they constrain structure, enforce grounding, and keep two authors (or the same author twice) consistent. If a rule here merely restates something Opus already knows, it does not belong here.

> Guardrail, not tutorial. Every law is a *constraint on output*, with a *test* to detect a breach and, where it exists, the *research/grounding* that justifies it.

---

## The grammar — six kinds, one home each

The richness is factored into six artifact kinds. **Every fact lives in exactly one home. Cross-references are by id or name — never a copy.** This is the DRY law of the kit itself.

| File | Owns | Never contains |
|---|---|---|
| [`spine.md`](spine.md) | **Process** — the ordered steps of A and B, each citing law ids + KG reads + output artifact + gate | law text, numbers, primitive definitions |
| [`laws.md`](laws.md) | **Operation invariants** — `R-CHP-*` (A) and `R-BLU-*` (B) | grounding laws (→ provenance), numbers (→ levers), primitive definitions (→ vocabulary) |
| [`vocabulary.md`](vocabulary.md) | **Named primitives** — tropes, sections, applet stages, content-types, pedagogy templates, screen roles | invariants (those are laws), tunable numbers |
| [`levers.json`](levers.json) | **Tunable numbers** — every threshold, budget, count, toggle | prose, laws |
| [`provenance.md`](provenance.md) | **Grounding + identity contract** — `R-GND-*`, the dual-ID scheme, the tag vocabulary, the badges | operation-specific laws |
| [`references.md`](references.md) | **Evidence layer** — the DOI-verified citations each law cites by key, + the law→grounding map | law text, process |

A law says *"a journey uses at most `lever:max_contexts_per_learn_journey` concrete contexts"* — the number is in `levers.json`, the law is in `laws.md`, and neither restates the other. A law says *"every trope instance conforms to its registry record"* — the trope's `position_rule` lives in `vocabulary.md`, enforced once by `R-BLU-02`.

**Why single-home matters here specifically.** The source system (ACRLDS) had real duplication: the screen-density rule appeared in both `blueprint_guide.json` and `media_insertion_heuristics.md`; the journey budget was `20` minutes in the CBSE skill and `30` in the system lever (a live conflict); the review skill kept *"verbatim copies … [that] drift until re-synced."* This kit removes those by construction — one number, one home; one law, one id.

## Grounding — how backed is each law (honest)

Not every law is a research claim, and the kit says which is which. Each law in `laws.md` carries a **Grounding** line of one of three types (full contract in `references.md`):

- **`literature:<keys>`** — the guardrail rests on a peer-reviewed finding. Every DOI in `references.md` was **verified against Crossref** on 2026-09-04 (title/author/year confirmed). The pedagogical laws — CPA (`R-BLU-03`), screen density (`R-BLU-07`, cognitive load), scaffolding fade (`R-BLU-04`), context coherence (`R-BLU-06`, variation theory), practice threading (`R-CHP-10`, spacing/interleaving/retrieval), Math_Trap (`R-BLU-02`, conceptual change), explore-before-explain (`R-BLU-19`, productive failure), worked examples (`R-BLU-13`), feedback (`R-BLU-12`) — carry primary sources. The ACRLDS `docs/foundation` names these frameworks; this kit supplies the literature it stops short of citing.
- **`convention`** — a house delivery/engineering rule for consistency or buildability (the sandwich, locked fields, coverage-closes-at-zero, dual-ID, tag contracts). **No theory is claimed, and none is implied.** ~half the laws; that is correct, not a gap.
- **`content-grounded`** — the *content* the law pulls is itself KG-cited per row (`source_citation` + `source_url` + `evidence_strength`), enforced by `R-GND-01/05`. The strongest, most-verifiable layer.

So: **not loose notes** (the content layer is auditable per-row, the pedagogical laws carry verified DOIs) and **not over-claimed** (conventions are labeled as conventions). One honesty flag: a few `Why:` lines are the author's own gloss and are marked as rationale, not sourced findings.

---

## KG-native assumptions

This kit assumes the **Knowledge Graph is the single source of record**. Everywhere the source system said "KB" (its private D1), this kit says **KG**, and:

1. **Substrate reads come from the KG.** Misconceptions, IAS patterns, convention differences, LOs, curriculum standards, prerequisite edges, and lesson/asset extracts are read from the KG's own verbs (`kg_list_misconceptions`, `kg_list_ias_patterns`, `kg_list_convention_differences`, `kg_list_los` / `kg_get_lo`, `kg_lesson_full`, `kg_list_ai_tags`, `kg_lo_neighborhood`).
2. **Textbooks come from the KG source-doc layer**, not a pasted PDF: `kg_list_source_docs` → `kg_get_source_outline` → `kg_get_source_pages` / `kg_search_sources`. The textbook is grounded and cited by `doc_id` + page, under the same provenance contract as every other claim. (See `R-CHP-01`, `R-GND-05`.)
3. **`false_friends`, `visual_insight_records`, `interactive_landscape` are assumed ported into the KG** as first-class nodes, FK'd / tagged to LOs (surfaced via `kg_list_ai_tags` or LO-neighbourhood edges). The laws reference them as KG reads; they no longer live in a side store.
4. **The proposed-node path replaces `CRX.*`.** When the chapter needs an LO/component/misconception the KG lacks, author it as a **proposed** node (`state: ai_proposed`, `kg_write_candidate: true`) — the KG's own `create_lo` / `bulk_create_*` authoring path, gated by human approval. The proposed vs resolved distinction is a hard provenance signal (`R-GND-01`).

**Integration intent (status: DRAFT).** The end-state is that this kit is **KG-native law the delivery side reads** — the seat and the (KG-sourced) research pipeline both obey one catalogue, enforced at three seams (below). Nothing here is wired yet; this is the reviewable design artifact.

---

## How every law reads

```
### R-BLU-07 · Screen density ceiling            [HARD]
Law.    One major idea, one visual context, one student action per screen.
Detect. >2 sentences to describe the screen; ≥2 worked examples on one screen;
        setup+reveal on one screen; ≥2 visual models on one screen.
Test.   Hand the screen to an untrained first-year teacher — presentable in 3 min?
Relax.  Placeholder screens exempt (developer brief, not student copy).
KG.     — (structural; no KG read)
Seam.   compile (counts density signals) + prompt (self-check).
Why.    Cognitive-load: split attention + redundancy effects; a dense screen
        loses both teacher and learner.
```

- **`[HARD]`** = invariant; a breach blocks the artifact. **`[SOFT]`** = heuristic; a breach is flagged for author judgment, never auto-failed.
- **Seam** = where the guardrail is enforced: `compile` (deterministic pass, zero-LLM), `prompt` (instructed into the generator), or `kg` (a KG-side constraint/validator). Most laws name more than one.
- **Relax** = the declared, in-law exceptions — usually keyed to `content_type` (Learn / Practice / Challenge) or node kind. Exceptions live *in the law*, never as author folklore.
- **Why** = the research/grounding or the house-rationale. Present only where it adds signal (a guardrail earns its place by its rationale).

## ID scheme

| Prefix | Family | Home |
|---|---|---|
| `R-GND-*` | Grounding + identity (cross-cutting) | `provenance.md` |
| `R-CHP-*` | Operation A — chapter research + sequence | `laws.md` |
| `R-BLU-*` | Operation B — journey + applet blueprint | `laws.md` |

Content structure carries **stable taxonomic ids** (trope names, section names, applet-stage names, screen roles, KG node ids) defined once in `vocabulary.md`. Laws reference those names; they are never redefined inline.

## Enforcement seams

1. **`compile`** — a deterministic, zero-LLM pass over the produced JSON. Enforces every structural `[HARD]` law that is machine-checkable (contiguity, sandwich presence, tag uniqueness, budget arithmetic, provenance completeness).
2. **`prompt`** — the guardrail is instructed into the generator so the model plans within it. Every `[SOFT]` law and every judgment-bearing `[HARD]` law rides here.
3. **`kg`** — a KG-side constraint or validator (e.g. `no-invented-ids` resolves against real KG nodes; proposed nodes route through the KG's authoring gate).

A law is only as strong as its strongest seam. Laws that are `compile`-checkable are the backbone; `prompt`-only laws are guardrails on judgment.

## Provenance of the kit itself (where each family was mined from)

So the kit is auditable back to the source system, one place, no per-line clutter:

| Family | Mined from (ACRLDS) |
|---|---|
| `R-GND-*`, dual-ID, tags, badges | `.claude/skills/cbse-chapter-research/references/{codification,provenance}.md`; `rules/{kb_gap_handling,delivery_language,concept_attribution}.*` |
| `R-CHP-*` | `config/rubric/{chapter_sequence_guide,research_synthesis_guide,lo_criteria}.json`; `rules/{scope_discipline,module_sequencing_rules,lo_code_alignment,textbook_floor_principle,module_annotation_schema}.*`; the chapter-research SKILL spine |
| `R-BLU-*` | `config/rubric/blueprint_guide.json`; `rules/{media_insertion_heuristics,module_level_tropes,dev_note_anchoring,convention_requirements,screen_tagging_protocol,visual_model_protocol}.*`; the de-scored `test` invariants of `{journey,applet}_gates.json` |
| `vocabulary.md` | `blueprint_guide.json` (seven_tropes, module_sections, applet_six_stages, content_type_structure), `pedagogy_structure.md`, `screen_role_observations.json` |
| `levers.json` | `config/levers/{pedagogical,kb,content_scope}.json`, `blueprint_guide.json` `pacing` block |

Rubrics, scores, weights, verdict thresholds, and the review passes are **deliberately excluded** — this kit is the authoring guardrail, not the evaluator.