@graffiticode/l0175 0.2.0

package/spec/template.gc

@@ -0,0 +1,67 @@
+/* Revised: 2026-06-20 */
+target c1-t4
+passage "The Tide Pool"
+type literary
+/* lines are PARAGRAPHS (auto-numbered 1..N). EBSR Part B sources add a `quote` with the exact
+   supporting sentence so options stay sentence-tight while `line` points at the paragraph. */
+lines [
+  "Mara crouched at the edge of the tide pool, ignoring the picnic her family had spread out behind her. Her brother called twice, but she did not turn around. A tiny crab scuttled under a rock, and Mara smiled for the first time all day."
+  "She had spent the whole car ride staring out the window, saying nothing. Now her fingers traced the cold water as if the pool were the only thing that mattered. \"Five more minutes,\" she whispered, though no one was listening."
+  "Behind her, paper plates rustled and her mother laughed at someone's joke. Mara did not hear them."
+]
+claims [
+  claim id "c1" status supported dimension character subject "Mara" standard rl-1 dok r-dok3
+    text "Mara is more interested in the tide pool than in her family's picnic."
+    rationale "Paragraphs 1 and 2 show Mara absorbed by the tide pool while she ignores her family."
+    cites ["e1" "e2" "e3" "e4"] {}
+  claim id "c5" status supported dimension character subject "the brother"
+    text "Mara's brother wants her attention."
+    cites ["e2"] {}
+  /* Distractors target the question(s) they foil (here, all foil the Mara items q1/q2/q3). */
+  claim id "c2" status distractor error-type misreads-detail plausibility 0.85 targets ["q1" "q2" "q3"]
+    text "Mara is angry at her brother for calling her."
+    rationale "Misreads 'she did not turn around': absorption, not anger."
+    cites ["e2"] {}
+  claim id "c6" status distractor error-type misreads-detail plausibility 0.6 targets ["q1" "q2" "q3"]
+    text "Mara is bored and impatient to leave."
+    rationale "Misreads her stillness as boredom; the crab makes her smile — delight, not boredom."
+    cites ["e6"] {}
+  claim id "c3" status distractor error-type erroneous-inference plausibility 0.55 targets ["q1" "q2" "q3"]
+    text "Mara dislikes spending time outdoors."
+    rationale "Over-generalizes from her quiet to a dislike her smile at the crab contradicts."
+    cites ["e6"] {}
+  claim id "c7" status distractor error-type erroneous-inference plausibility 0.5 targets ["q1" "q2" "q3"]
+    text "Mara wishes she were somewhere else with her friends."
+    rationale "Invents an off-text desire; nothing in the passage mentions friends."
+    cites ["e7"] {}
+  claim id "c4" status distractor error-type faulty-reasoning plausibility 0.45 targets ["q1" "q2" "q3"]
+    text "Because Mara whispers, she must be afraid of her family."
+    rationale "Whispering is treated as fear without textual support."
+    cites ["e5"] {}
+  claim id "c8" status distractor error-type faulty-reasoning plausibility 0.4 targets ["q1" "q2" "q3"]
+    text "Because Mara ignores the picnic, she must not love her family."
+    rationale "Leaps from one moment of focus to a sweeping claim about her feelings."
+    cites ["e6"] {}
+]
+evidence [
+  source id "e1" line 1 quote "Mara crouched at the edge of the tide pool, ignoring the picnic her family had spread out behind her." status directly-supports supports ["c1"] {}
+  source id "e2" line 1 quote "Her brother called twice, but she did not turn around." status supports-wrong-claim supports ["c1" "c2"]
+    rationale "Real evidence, but props up the 'anger' misreading, not the inference." {}
+  source id "e3" line 1 quote "A tiny crab scuttled under a rock, and Mara smiled for the first time all day." status directly-supports supports ["c1"] {}
+  source id "e4" line 2 quote "Now her fingers traced the cold water as if the pool were the only thing that mattered." status directly-supports supports ["c1"] {}
+  source id "e5" line 2 quote "\"Five more minutes,\" she whispered, though no one was listening." status supports-wrong-claim supports ["c4"]
+    rationale "Her whisper is real, but it shows focus, not fear." {}
+  source id "e6" line 3 quote "Behind her, paper plates rustled and her mother laughed at someone's joke." status irrelevant supports [] {}
+  source id "e7" line 3 quote "Mara did not hear them." status irrelevant supports [] {}
+  source id "e8" line 2 quote "She had spent the whole car ride staring out the window, saying nothing." status irrelevant supports [] {}
+]
+outcomes [
+  outcome id "q1" type ebsr dimension character subject "Mara" standard rl-1 focus "c1"
+    stem "Which of these inferences about Mara is supported by the passage?"
+    stem-b "Which sentence(s) from the passage best support your answer in Part A?" {}
+  outcome id "q2" type short-text dimension character subject "Mara" standard rl-1 focus "c1"
+    stem "What inference can be made about Mara? Explain using key details from the passage to support your answer." {}
+  outcome id "q3" type hot-text dimension character subject "Mara" standard rl-1 focus "c1"
+    stem "Click on the statement that best provides an inference about Mara that is supported by the passage." {}
+]
+{}..

package/spec/unparse-hints.json

@@ -0,0 +1,3 @@
+{
+  "LINES": "treat lines as paragraphs in the original passage"
+}

package/spec/usage-guide.md

@@ -0,0 +1,111 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+# L0175 Usage Guide
+
+_Revised: 2026-06-18_
+
+Agent-facing guide for authoring L0175 programs. Read this before composing a `create_item` prompt or an `update_item` modification.
+
+## Overview
+
+L0175 is a content-composition language for 5th-grade English Language Arts assessment items (Smarter Balanced spec ELA · Grade 5 · Claim 1 · Reasoning & Evidence). One language serves **multiple learning targets**; **every program first declares a top-level `target`**: `c1-t4` (Target 4 — *literary* texts, RL standards, dimensions like character/theme/point-of-view) or `c1-t11` (Target 11 — *informational* texts, RI standards, dimensions like relationships-interactions/author-use-of-information/point-of-view/purpose). Choose the target from the request (literary vs. informational text and the skill assessed); the dimensions, standards, and stem catalog (`stems.md`) are then scoped to that target, and mixing targets' vocabularies is a compile error. It is **item-first**: after picking the target you compose the questions (`outcome`s) first — each with a unique `id`, a `focus` naming its correct claim, and an explicit `stem` (and `stem-b` on EBSR) instantiated from the guideline's Appropriate-Stem catalog (`stems.md`) — then author the supported `claim`s and a *superset* of distractor `claim`s, each tagging the question(s) it foils via `targets`, plus evidence `source`s. The compiler then *composes* each outcome deterministically: it takes the correct claim from `focus`, draws that question's foils ONLY from the distractors that `targets` it, uses the authored stem, and assembles a finished item in one of three task models: `ebsr` (two-part evidence-based selected response), `hot-text` (select-text), or `short-text` (constructed response). One passage + superset can yield several items, each with its own bound foil set. The compiler performs no generation and no stem synthesis — it selects, validates against the guideline, and warns when a question's pool falls short. Distractors are tagged by the SBAC error taxonomy (Part A: `misreads-detail`, `erroneous-inference`, `faulty-reasoning`; Part B: `supports-wrong-claim`, `irrelevant`), each carrying a rationale; composition picks foils for error-type coverage and couples Part B evidence to the claims it plausibly supports. **For each EBSR/Hot-Text question author at least 5 viable distractors that `targets` it (aim for 5–8, over-generating since some are filtered as near-duplicates or accidentally correct) — covering all three error types with ≥2 alternatives in at least two of them, and giving each a `plausibility` score (0–1). An item draws only 3 foils, so a richer targeted pool yields stronger items; fewer than 3 targeting a question is a hard error, fewer than 5 a warning. Likewise, for EBSR Part B author at least 5 non-supporting evidence lines (`supports-wrong-claim` + `irrelevant`) so the compiler can choose the most tempting 3 foil options. No-giveaway rule: at least one of those `supports-wrong-claim` lines must list BOTH the correct claim's id AND a distractor's id in its `supports` (a line that seems to support the right answer but actually backs a misreading) — otherwise the correct evidence line stands alone, Part B telegraphs Part A, and the compiler warns "possible A↔B giveaway." Do not make every wrong-claim line point only at distractors.**
+
+**Targets are different skills — pick the one the request assesses.** Beyond the two Reasoning &
+Evidence targets above (`c1-t4` literary, `c1-t11` informational — infer/conclude and justify with
+evidence), L0175 also composes **`c1-t9` — Central Ideas** (informational): a *different* skill —
+synthesize and condense (the main/central idea, the key details that build it, and summary), NOT
+inference. Use `c1-t9` when the request is about the **main idea**, **most important details**, or a
+**summary**; dimensions `central-idea`/`key-detail`/`summary`, standards `ri-1`+`ri-2`, DOK 2 (3 for
+the written summary). Its distractors are a **significance** taxonomy — usually *true* statements
+that simply aren't central: `too-narrow` (a supporting detail mistaken for the main idea),
+`too-broad` (an overgeneralization/off-topic), `misreads-detail`, `insignificant` (a minor detail
+that doesn't belong in a summary). T9 item types are `multiple-choice` (pick the central idea),
+`multi-select` (choose the two sentences that belong in a summary — `focus` is a **list**), `ebsr`
+(central idea → supporting detail), `short-text` (summary), and single-part `hot-text` (click the
+sentence(s) that show the main idea — the `focus` claim's directly-supporting `source`s are the
+correct selection). Two new item types — `multiple-choice` (4 options, one correct) and
+`multi-select` (5–6 options, an exact correct set) — are single-part: author the `stem` and a
+`focus`, no Part B.
+
+L0175 also composes **`c1-t8` — Key Details** (informational): the inference/conclusion is **GIVEN
+in the stem** and the student selects the supporting **evidence** (the answer is *evidence*, not a
+chosen statement). Use `c1-t8` when the request **states an idea and asks which detail/sentence
+supports it**; dimension `supporting-evidence`, standards `ri-1`+`ri-7`, DOK 1–2, item types
+`multiple-choice`, `multi-select`, and **single-part `hot-text`** (no Part A). Author ONE supported
+`claim` = the given inference (its `focus`), state it in the `stem`, and author `source`s as the
+options: `directly-supports` = correct evidence (with a `quote`), `supports-wrong-claim`/`irrelevant`
+= distractor evidence. No distractor claims.
+
+L0175 also composes **`c1-t10` — Word Meanings** (informational): the question asks for the
+**meaning of a targeted word/phrase in context**, so the answer choices are **meanings**, authored
+as a dedicated `word`/`meaning` structure (not claims). Use `c1-t10` when the request asks **what a
+word/phrase means**; dimension `word-meaning`, standards `ri-4` + the L-4 family (`l-4a` context /
+`l-4b` roots & affixes / `l-5c` word relationships / `l-4c` reference), DOK 1–2, item types
+`multiple-choice`, `multi-select`, and `hot-text` (click the word matching a given definition — the correct word is `focus` with its paragraph's `line`; author the distractor candidate words either as more single-word `word`s OR as the focus word's distractor `meanings` whose `text` is the candidate word itself (a single word, not a definition), ALL appearing in that one paragraph. The compiler shows the paragraph and makes the candidate words clickable, focus correct; if no candidate words are found it falls back to making every content word a choice. The `stem` is only the instruction + definition — never paste the paragraph into the stem). Author a top-level
+`words` list: a `word` (the targeted word, `line`/`quote` for context) with `meanings` — one (MC) or
+≥2 (Multi-Select) `status correct` meanings + `status distractor` meanings (each with a T10
+`error-type` — `other-meaning`/`misinterprets`/`wrong-context` — and a `rationale`). The outcome's
+`focus` names the word; state the word and its context sentence in the `stem`.
+
+**Write at the target grade level.** The grade is the guideline's grade (the target's — Grade 5 for `c1-t4`/`c1-t11`) unless the user's prompt asks for a different grade, in which case author a top-level `grade <n>`. Match the passage AND all question text to that grade: short, mostly simple/compound sentences; concrete, high-frequency vocabulary; an inference drawn from **specific details in the text**, not college-style literary or rhetorical analysis. DOK 3 means strategic reasoning *within* grade-level text — not harder text. The compiler estimates the passage's reading level and warns when it runs above the target grade. See **Grade-appropriate reading level** below.
+
+**Supply the passage already split into paragraphs.** When a request includes or describes the passage text, break it into its paragraphs and keep those breaks — each paragraph becomes one numbered `lines` entry and the rendered passage preserves that paragraph structure. The code generator maintains the paragraphs you provide; it does not re-flow a wall of text into one block or re-chunk it. Separate paragraphs with a blank line (or clearly mark each one) so they survive into the final passage. **Keep paragraphs even for Hot Text** — the compiler segments each paragraph into sentences and makes each one individually selectable in Part B, so the passage keeps its paragraph layout; do not author the passage as one-sentence lines.
+
+When composing a request, declare the `target`, then author the passage and outcomes (with their stems) first, then the inference graph (supported claims, then the targeted distractors), then the evidence. The program is one flat builder chain: top-level forms (`target`, `passage`, `type`, `lines`, `claims`, `evidence`, `outcomes`) thread a single continuation and the whole program ends with one `{}..`. Inside the `claims`/`evidence`/`outcomes` lists, each element (`claim`/`source`/`outcome`) is its own attribute chain terminated by its own `{}`. Attribute values that are free text (`text`, `rationale`, `subject`, `stem`, the passage heading) or id labels (`id`, `focus`, `cites`, `supports`, `targets`) are quoted strings; closed-enum values (`target`, `type`, `status`, `dimension`, `error-type`, `standard`, `dok`) are bare kebab-case identifiers (e.g. `c1-t11`, `ebsr`, `directly-supports`, `ri-1`).
+
+In scope: SBAC Grade 5 · Claim 1 for targets **T4** (Reasoning & Evidence, literary, RL), **T11** (Reasoning & Evidence, informational, RI), **T9** (Central Ideas, informational, RI-1/RI-2), **T8** (Key Details, informational, RI-1/RI-7 — given-inference → evidence selection), and **T10** (Word Meanings, informational, RI-4/L-4 — meaning of a targeted word, authored as `word`/`meaning`); a single passage; the per-target dimensions and distractor taxonomy; item types `ebsr`, `hot-text`, `short-text`, `multiple-choice`, `multi-select` (allowed set varies by target); DOK r-dok1..r-dok3. Out of scope: other claims/grades or Claim-1 targets beyond T4/T11/T9/T8/T10; multi-word-phrase candidates in T10 click-the-word; dual-text stimuli; compile-time LLM generation; auto-scoring of short text; cross-language composition.
+
+## Grade-appropriate reading level
+
+Items must read at the grade the guideline targets. **Resolving the grade:** use the target/guideline's grade — Grade 5 for the current `c1-t4` and `c1-t11` guidelines — unless the user's prompt names a different grade, in which case author a top-level `grade <n>` (e.g. `grade 4`). The compiler echoes the resolved grade on the output and estimates the passage's reading level, warning when it reads above target.
+
+Author the passage **and** every claim, option, and rationale to that grade (figures below are the Grade-5 instance; scale with the grade):
+
+- **Reading level** — match the CCSS text-complexity band for the grade. Grade 5 ≈ Lexile **740–1010L**, Flesch–Kincaid grade **4.5–6.0**; don't exceed about one grade above target.
+- **Sentences** — mostly simple and compound; average roughly `2·grade + 2` words (~12–16 at Grade 5), and avoid more than the occasional sentence past ~22 words or stacked subordinate clauses.
+- **Vocabulary** — concrete, high-frequency words a student that age knows; at most a few grade-appropriate Tier-2 words made clear by context. Avoid abstract/academic (Tier-3) diction above grade (e.g. *ambivalence*, *juxtaposition*, *ostensibly*).
+- **Passage length** — a single passage ≈ 150–350 words at Grade 5; scale with the grade.
+- **Figurative language** — sparing and accessible; no dense or layered metaphor.
+- **Reasoning, not just prose** — DOK 3 is *strategic thinking within grade-level text*, not college-level analysis. The correct inference must come from **concrete textual details** (what a character does or says, a stated cause and effect), not abstract thematic or authorial-technique critique beyond grade. Keep distractor and option text in the **same register** as the passage — a wrong answer that sounds more academic than the text gives itself away.
+
+## Vocabulary Cues
+
+Say this to get that:
+
+- **Target** — `target c1-t4` (literary, Reasoning & Evidence), `target c1-t11` (informational, Reasoning & Evidence), `target c1-t9` (informational, Central Ideas), `target c1-t8` (informational, Key Details — given-inference → evidence), or `target c1-t10` (informational, Word Meanings — meaning of a targeted word); required, first top-level form. Selects the dimensions, standards, distractor taxonomy, DOK, item types, and stem catalog.
+- **Grade** — optional top-level `grade <n>` (e.g. `grade 5`). Defaults to the target/guideline's grade; author one only to override when the user asks for a different grade. Sets the reading-level target the compiler checks the passage against.
+- **Passage** — `passage "Title"` sets the heading; `type literary` (or `informational`, matching the target); `lines [ "..." "..." ]` are the passage **paragraphs** — one entry per paragraph, auto-numbered from 1. Always split by paragraph, including for Hot Text: the compiler segments each paragraph into sentences and exposes each sentence as a Part B selection, so the passage keeps its paragraph format. For EBSR Part B, evidence sources carry a `quote` with the exact supporting sentence so options stay sentence-tight while `line` points at the paragraph.
+- **Outcome** — the question, composed first. `outcome id "q1" type ebsr dimension character subject "Mara" focus "c1" stem "Which of these inferences about Mara is supported by the passage?" stem-b "Which sentence(s) from the passage best support your answer in Part A?" {}`. `id` is the handle distractors target; `focus` names the correct claim; `stem` (and `stem-b` on EBSR) come from `stems.md`. Vary `type` (`ebsr` / `hot-text` / `short-text`) for different task models. **Keep the Part A stem a neutral question** — fill the template's slot with the subject/skill only, and do **not** echo the correct option's wording (if the stem restates the answer, it gives it away). Paraphrase so stem and key share only the subject; the compiler warns when the stem reuses most of the correct option's words. Applies to every Hot Text and EBSR question, across all targets. **For Hot Text, Part A asks for the best STATEMENT** ("Click on the statement that best provides an inference about [X]…") whose options are inference claims — it is NOT a "click the sentences" instruction (that's Part B, fixed by the compiler). If a request says "select the sentences that show [X]", translate it: Part A is a statement prompt about [X], and the sentences that show [X] are `directly-supports` evidence (with exact `quote`s) that become Part B's answer. The compiler warns when a Hot Text Part A stem mentions sentences.
+- **Claim** — a candidate inference statement. Supported: `claim id "c1" status supported dimension character subject "Mara" text "..." cites ["e1" "e2"] {}`. A distractor adds `error-type`, a required `rationale`, and `targets` (the question id(s) it foils): `claim id "c2" status distractor error-type misreads-detail targets ["q1"] text "..." rationale "..." cites ["e2"] {}`.
+- **Evidence source** — a passage line tagged by its support role. `source id "e1" line 1 status directly-supports supports ["c1"] {}`. Statuses: `directly-supports`, `supports-wrong-claim`, `irrelevant`. An optional `rationale` explains a foil. For **Hot Text**, give each `directly-supports` source a `quote` naming the exact supporting **sentence** so that sentence is marked correct in Part B; a `directly-supports` source with no `quote` marks every sentence of its `line` correct. Part B asks for an **exact number** of sentences (one less than the valid count, floored at 1, capped at 3) and **any selection of that many from the valid set is correct** (a superset) — so **author ≥3 directly-supporting sentences** so the asked count is ≥2 and students aren't forced to find every one.
+- **Dimensions (c1-t4)** — `character`, `setting`, `event`, `point-of-view`, `theme`, `topic`, `narrators-feelings`, `character-relationship`.
+- **Dimensions (c1-t11)** — `relationships-interactions`, `author-use-of-information`, `point-of-view`, `purpose`, `authors-opinion`.
+- **Dimensions (c1-t9)** — `central-idea`, `key-detail`, `summary`.
+- **Dimensions (c1-t8)** — `supporting-evidence` (the answer is evidence; the inference is given in the stem).
+- **Dimensions (c1-t10)** — `word-meaning` (the answer is a meaning; authored via `word`/`meaning`).
+- **Word / meaning (c1-t10)** — `words [ word id "w1" text "aqueduct" line 1 quote "…" meanings [ meaning id "m1" status correct text "a water channel" {} meaning id "m2" status distractor error-type other-meaning text "a boat" rationale "…" {} ] {} ]`; the outcome's `focus` names the word.
+- **Item types** — `ebsr` (two-part: statement → evidence), `hot-text` (R&E/Central-Ideas: click the supporting/main-idea sentences; Key Details: click the evidence sentences; Word Meanings: click the word matching a definition), `short-text` (constructed response), `multiple-choice` (one correct, single-part), `multi-select` (exact correct set, single-part). MC/Multi-Select have no Part B. The allowed set is per-target (the compiler rejects others).
+- **Central Ideas (c1-t9) distractor `error-type`** — `too-narrow`, `too-broad`, `misreads-detail`, `insignificant` (true-but-not-central); R&E targets use `misreads-detail`/`erroneous-inference`/`faulty-reasoning`.
+- **Program terminator** — top-level forms chain with no `{}` between them; the program ends with a single `{}..`.
+
+## Example Prompts
+
+- *"Write an EBSR item about the main character's motivation in a short story about a girl at a tide pool."* → `target c1-t4`, `ebsr`
+- *"From the same passage, also produce a short-text constructed-response item and a hot-text item."* → `short-text`, `hot-text`
+- *"Add a faulty-reasoning distractor that mistakes the character's quiet focus for fear."* → distractor `claim`
+- *"Make an EBSR item about how the author uses evidence to support a point in an informational article about bridges, standard ri-8."* → `target c1-t11`, `dimension author-use-of-information`
+- *"Write an item about the relationships between the events in a history passage."* → `target c1-t11`, `dimension relationships-interactions`
+- *"Which sentence best states the main idea of this article? (multiple choice)"* → `target c1-t9`, `type multiple-choice`, `dimension central-idea`
+- *"Make a multi-select asking for the two sentences that belong in a summary."* → `target c1-t9`, `type multi-select`, `dimension summary`, `focus` is a list of the two correct claims
+- *"The article says aqueducts brought water to distant cities — which detail best supports that? (multiple choice)"* → `target c1-t8`, `type multiple-choice`, `dimension supporting-evidence`; the inference goes in the `stem`, the options are `source`s
+- *"Make a click-the-sentence item where students select the evidence for a stated conclusion."* → `target c1-t8`, `type hot-text` (single-part), `dimension supporting-evidence`
+- *"What does the word 'aqueduct' mean as used in this article? (multiple choice)"* → `target c1-t10`, `type multiple-choice`, `dimension word-meaning`; a `word` with candidate `meaning`s, `focus` names the word
+- *"Read the paragraph below. Click the word that means 'a channel that carries water'."* → `target c1-t10`, `type hot-text` (click-the-word); author the candidate `word`s (correct one is `focus` with its paragraph's `line`, plus a few distractor candidate words from the same paragraph); definition in the stem, passage NOT in the stem
+- *"Keep the passage at a 4th-grade reading level."* → top-level `grade 4`; author shorter sentences and simpler vocabulary (the default is the guideline's Grade 5)
+
+## Out of Scope
+
+- **Other targets / grades / claims** — L0175 covers G5 · Claim 1 · Reasoning & Evidence, targets T4 (literary) and T11 (informational). Other targets belong in their own dialects.
+- **Dual-text stimuli** — a single passage only in this version.
+- **Compile-time generation** — the compiler selects and validates authored content; it does not invent claims, distractors, or evidence.
+- **Auto-scoring** — short-text responses are hand-scored against the rubric; the compiler emits the rubric only.
+- **Cross-language composition** — each item runs in exactly one dialect.