E-turo Artifact Specification

The contract every grade-level artifact set must satisfy. Grade 4 Mathematics is the reference implementation — see grades/g04-math/.

1. Scope decision: Mathematics as the spine

The brief asks for one artifact set per grade level, Grades 1–10. A grade level is not a subject, so a subject had to be chosen. Mathematics is used, because:

• It is the only learning area present in all ten grades of MATATAG (Language/Reading and Literacy exist only in Grades 1–2; Science begins at Grade 3; Araling Panlipunan, EPP/TLE and MAPEH begin at Grade 4). Any other choice leaves gaps in the 1–10 sequence.
• Its three content domains are stable across all ten grades, so a single template can carry a genuine vertical progression instead of ten unrelated documents.
• It is the strongest fit for a browser-based interactive game — numeric answers are automatically checkable, which makes real-time formative feedback possible without a server.

The same template works for any other learning area. Swapping subjects is a content change, not a structural one.

Since written: Science, Grades 3–10, is also built. Mathematics remains the spine — it is still the only area covering all ten grades — but the repository now holds two learning areas, and a grade number is no longer an identity. g03-math and g03-science are both "Grade 3"; the unique key is the directory slug. §7 records what that cost. The claim that swapping subjects is "a content change, not a structural one" turned out to be about four-fifths true, and the remaining fifth is documented rather than quietly patched.

2. Directory layout

One folder per grade, named g<NN>-<subject>:

grades/g04-math/
├── index.html             Grade landing page — links the artifacts
├── syllabus.md            Artifact 1
├── lesson-plan-ilaw.md    Artifact 2a — the five-day week, in the prescribed format
├── lesson-plan.md         Artifact 2b — day 1, at teaching depth
├── assessment.md          Companion — TOS, papers with keys, weekly check, rubrics
├── class-record.html      Companion — raw scores in, grade out (see §3.2d)
├── slides.html            Artifact 3.1 — self-contained deck
├── game.html              Artifact 3.2 — self-contained interactive game
├── offline-activities.md  Artifact 3.3 — 3 individual + 2 group
├── worksheet.html         Companion — the printable page the whole class holds
├── worksheet-remediation.html  Companion — the lower-floor route to the same competency
├── wall-chart.html        Companion — printable classroom chart (source)
├── wall-chart.png         Companion — rendered at 2× for printing
├── wall-chart.pdf         Companion — true A4 landscape
├── misconceptions-card.html    Generated — the desk card (§3.8)
├── observation-card.html       Generated — cut-apart slips (§3.9)
├── rubric-poster.html          Generated — what good looks like, on the wall (§3.10)
└── parent-guide.html           Companion — one page that leaves the building (§3.11)

A Key Stage 1 grade adds a NAME.en.md beside each of the five teacher documents and an index.en.html beside the grade index, plus NAME.en.html beside the two teacher-facing generated cards — and adds nothing beside the learner-facing artifacts, which a child reads in the mother tongue. All three mother-tongue grades must translate the same set; a family translated in two of them and not the third is a hole a reader falls through, and the deploy test names it. Grade 1 ships no class-record.html; see §3.2d.

Three of these are generated, not written — see §3.8–3.10. Do not edit them by hand: node tools/cards.mjs --check fails if you do, and the content belongs to the document each one derives from.

3. Artifact requirements

3.1 Syllabus (syllabus.md)

Full-year, term-organised. Must contain:

3.2 Lesson plan (lesson-plan.md)

A single 45-minute session, using the official MATATAG Lesson Exemplar headings — I, II, III (A–D), IV (A–C) — with minute-level timings that sum to 45. Must contain:

• Explicit link to the artifacts used at each stage (slides, game, offline activity)
• Anticipated misconceptions with a scripted teacher response for each
• Answer keys for everything learners are asked to do
• A differentiation block: below-level, on-level, above-level
• A no-electricity contingency — the lesson must run with chalk alone

3.2b Lesson plan, ILAW format (lesson-plan-ilaw.md)

Both formats ship. They do different jobs, and neither replaces the other.

DO No. 009, s. 2026 is reported to prescribe ILAW — Intentions, Learning Experiences, Assessment, Ways Forward — as the single lesson plan template for SY 2026–2027, replacing both the Daily Lesson Log and the Detailed Lesson Plan, and barring schools, divisions and regions from requiring any other. The Lesson Exemplar is DepEd's own teaching material; ILAW is what the teacher writes and files.

Making ILAW the week rather than the day is deliberate: the DLL it replaces was weekly, and it is the only version of the two that answers "what happens Tuesday?"

The crosswalk, which is lossless:

⚠️ The field list is reported, not read. The four section names are consistent across sources; the sub-fields a given division expects may differ. Both files carry that warning at the top. See source-catalogue.md §8.

Requirements specific to the ILAW file:

• Every day of the week accounted for, not only the day with full artifacts
• Assessment section states which component each instrument feeds, and at Key Stage 1 states plainly that there is no numerical mark
• Ways Forward carries remediation and enrichment as separate, named provisions — not a single "differentiation" paragraph
• Ends with an explicit next week dependency: what the following week assumes, and what to do if the class does not have it

3.2c Assessment pack (assessment.md)

One per grade. The content differs by key stage, and that difference is the point.

Both must contain: complete answer keys, rubrics for every performance task, and a "what is deliberately not here" section so an omission is visibly a decision.

3.2d Class record (class-record.html)

Key Stages 2–4 only. Grade 1 must not ship one — there is no number to record, and shipping one would invite a teacher to compute a mark the order forbids. test/deploy.test.js asserts its absence.

• Computes the initial grade from raw scores; the teacher enters nothing derived
• Transmutation is a year switch, not a constant
• Where the reported table has no anchor, it refuses to interpolate and says so rather than inventing a grade
• No storage, no network. Closing the tab discards the data; printing is the way to keep it

3.3 Slide presentation (slides.html)

Single HTML file. Requirements:

• No network dependency. No CDN, no webfonts, no external images. Opens from a USB stick.
• Keyboard navigation (← → Space Home End), on-screen controls, touch swipe
• Slide counter, progress bar, and a presenter-visible timing hint per slide
• Readable from the back of a classroom: minimum 24 px body text on slides, high contrast
• Print stylesheet that outputs one slide per page as a handout
• 12–18 slides for a 45-minute session

3.4 Browser-based game (game.html)

Single HTML file, no network dependency, no build step. Requirements:

• Directly assesses the same competency as the lesson plan — not a generic quiz
• Three rounds of escalating demand mapped to the lesson's sub-skills
• Mouse, touch, and keyboard input — Philippine classrooms use shared tablets and old desktops alike
• Immediate, specific feedback: not "Wrong" but why, tied to the misconception
• Question generation is randomised per session so the game is replayable and cannot be memorised
• A Teacher Panel at the end reporting per-round accuracy against the competency, so the game doubles as formative assessment evidence
• Runs at 320 px width (phone) through projector resolution
• No login, no data leaves the device

3.5 Offline classroom activities (offline-activities.md)

Three individual options and two group/team options. Every activity must state:

Group activities must additionally assign named roles to every member so that no learner is a spectator, and must work in a class of 45+ with fixed desks.

3.6 Wall chart (wall-chart.html → .png, .pdf) — companion piece

Not part of the five required artifacts, but every grade should ship one. A single A4 landscape sheet a teacher can print, laminate, and put on the wall for the whole term.

• Renders from HTML via node test/render-wall-chart.js — PNG at 2× and a true A4 PDF
• Carries the same visual system as the slides and the game, so the classroom wall and the screen reinforce each other
• Must survive a black-and-white photocopy: colour is the fast channel, never the only one
• Verified to fit one page with zero overflow

3.7 Learner worksheet (worksheet.html) — the page the whole class holds

The slides and the game are things learners are shown. This is the one every learner holds, writes on, and takes away. One printable A4 page.

It is deliberately one sheet for the whole class, tiered inside itself rather than split into an easier version and a harder one. Handing out two different sheets tells a room who is in which group; tiering within one sheet does not. Where a learner needs a different starting point rather than a shorter path, that is §3.12 — a separate route, not a second tier.

• Photocopy-safe: hatch patterns as well as colour, and no fill so light it vanishes at 50% toner
• The answer key lives on the page but never prints — .noprint, so the teacher reads it on screen and the child receives a clean sheet
• Ends with a diagnostic item that cannot be completed mechanically, marked as such for the teacher
• At Key Stage 1 the sheet carries no written instructions at all. The class cannot read. Every direction is spoken by the teacher and printed on the page for the teacher, in a screen-only box; what the child sees is pictures, boxes and numerals
• Fully usable without a printer: every item must be transcribable to a blackboard

3.8 Misconceptions desk card (misconceptions-card.html) — generated

The thing a teacher holds while walking the room. Nobody pages through three thousand words of lesson plan while a child stands at the desk waiting.

• Derived by tools/cards.mjs from the misconceptions table in lesson-plan.md. Every row, in order, with the where it shows column the plan already carries
• Never authored. Reword a misconception in the plan and the card follows; edit the card and --check fails
• A4 portrait, print rules, photocopy-safe
• Teacher-facing, so a Key Stage 1 grade also ships .en.html, generated from lesson-plan.en.md

3.9 Observation card (observation-card.html) — generated

Eight identical slips to cut apart, one per child, for recording what a learner actually said during the week.

• Derived from the success criteria in lesson-plan-ilaw.md — one tick box per criterion, so the card cannot list a standard the plan does not set
• Carries one instruction that is the whole point of the format: write the child's exact words, not your interpretation of them
• Must be usable with no JavaScript. A photocopy master that needs a script to draw its own boxes is not a photocopy master
• Teacher-facing; .en.html at Key Stage 1

3.10 Rubric poster (rubric-poster.html) — generated

The only artifact in the set that tells a learner what good looks like before they are judged against it, rather than after. A4 landscape, for the wall.

• Derived from the grade's own scale, never invented. Above Key Stage 1 that is the Term 1 performance-task rubric in assessment.md; at Key Stage 1, where grading is descriptive by order, it is the five A–E levels for the cluster covering the week actually taught
• Do not introduce a four-level Advanced/Proficient/Developing/Needs Support scale. It has no DepEd basis and contradicts the A–E scale used everywhere else here
• Learner-facing, so it ships in the mother tongue only — the child reading it off the wall reads the mother tongue

3.11 Parent guide (parent-guide.html) — the page that leaves the building

One printable page that goes home with the child, written for an adult who is not a teacher, may not have finished school, and has nothing in the house but ordinary objects.

• A ten-minute activity, named household objects, numbered steps, and what the adult says in quotation marks so it can be read aloud rather than improvised
• Three things to avoid, each drawn from a real misconception in that grade's lesson plan, each with what to do instead. A parent teaching a shortcut is the commonest way home help backfires
• Three observable signs it is working, in the child's likely words — not "understands place value"
• Never implies the parent should be teaching, or that the child is behind
• Written in the language the home reads, which at Key Stage 1 is the mother tongue and has no English copy

3.12 Remediation sheet (worksheet-remediation.html) — a different route, not a shorter one

For learners who did not get there with §3.7. Not the same tasks made easier and not half of a split worksheet: a different starting point to the same competency.

• Starts concrete — the first task needs no symbolic notation at all
• One new thing per task, four tasks rather than eight, large answer boxes
• Every task carries a fully worked example above it, so a stuck learner can copy the method and never the answer
• Ends where worksheet.html begins, so the bridge is visible to the teacher
• A real answer key covering every item, .noprint

4. Visual design

All student-facing artifacts follow DESIGN-PHILOSOPHY.md — the "Ten Times" system, in which the mathematics is the organising principle of the design rather than something the design merely decorates.

The three rules that matter most when building a new grade:

1. One colour system, used identically everywhere. A hue that means "hundreds" on a slide must mean "hundreds" in the game and on the wall chart. Consistency across surfaces is what turns colour into vocabulary; inconsistency is worse than no colour at all.
2. Show quantity truthfully. Where a value can be drawn to scale, draw it to scale even when the result is lopsided — the lopsidedness is usually the lesson.
3. Colour never carries meaning alone. Every colour-coded element is also labelled and positioned, for colour-blind learners and for photocopies.

Contrast is checked, not assumed: every hue clears 4.5:1 against its own tint and against white, and no two hues in a set sit close enough to be confused. Semantic red is reserved for "not yet" feedback and never used as a content colour.

5. Non-negotiables across all artifacts

1. One language per artifact set — never mixed. A set is written wholly in one language. No bilingual glosses, no translated headings in parentheses, no Tagalog activity names inside English prose, and no English round names inside Filipino prose.

   Grades	Language	Why
   1–3 (Key Stage 1)	Filipino or the regional mother tongue, wholly	MTB-MLE applies through Grade 3
   4–10	English, wholly	English is the medium of instruction for Mathematics from Grade 4

   Philippine English vocabulary is not language mixing and stays: barangay, sari-sari store, jeepney, peso, and the official learning-area names (Makabansa, Araling Panlipunan, Filipino, GMRC). These are the standard terms in DepEd's own English-language materials.

   There are exactly two ways a second language may appear, and they are different things.

   1a. A parallel set for another mother tongue. If a school's mother tongue is Cebuano, Ilocano or any of the nineteen DepEd recognises, the whole set — student artifacts included — is produced in that language in its own folder, fully translated. Never a mixed-language single copy.

   1b. An English reading copy of a teacher document. Written as a NAME.en.md sibling beside NAME.md, rendered by tools/render-docs.mjs, and reachable through a language switcher on the page. This is not a parallel set; it is the same set, readable by someone who is not going to teach from it. Three rules bound it:

   Rule	Why
   Teacher documents only — syllabus, lesson plan, offline activities	These are read by adults. Slides, games and wall charts face the child, and at Grades 1–3 an English copy of those is a route to projecting English at a class the curriculum says must be taught in the mother tongue. test/deploy.test.js fails if one appears.
   Spoken script is never translated	Lines the teacher says aloud stay in the mother tongue, verbatim, marked <span class="say" lang="fil">. Translating them yields a document that reads correctly and teaches in the wrong language — a failure that looks like an improvement in review, which is why it is asserted in the test suite rather than left to judgement.
   Whole pages, never half a page	Each variant is a complete document in one language. The switcher navigates between them; it never rewrites part of a page. A lang attribute on the page and on every preserved script span keeps screen readers honest.

   The .say spans and a short glossary of recurring phrases are the only place the two languages meet, and they meet as quotation, not as prose. Rule 1 is otherwise unchanged: no bilingual glosses in running text, no translated headings in parentheses.

   Where an English copy exists it is also the more authoritative one for competency wording, because the MATATAG curriculum guide is written in English: the English copy quotes it, the mother-tongue copy translates it. Writing the Grade 1 English syllabus is what surfaced a phrase the Filipino translation had dropped.

2. Offline-first. Every digital artifact is one file, opens with a double-click, and works with the Wi-Fi off. This is a design requirement, not a nice-to-have.

3. Philippine context. Pesos, sari-sari stores, jeepney fares, barangay populations, local place names. No imported word problems about dollars and yard sales.

4. Accessibility. Keyboard reachable, 4.5:1 contrast minimum, 44 px touch targets, no colour-only signalling, prefers-reduced-motion respected.

5. Print-ready. Teachers photocopy. Every artifact prints cleanly in black and white.

6. Honest sourcing. Where competency wording is paraphrased rather than quoted, the artifact says so. See §6 of the research brief.

7. A way to write back. Every artifact with a footer carries one line offering a way to report a mistake or say it was used with a class, generated by tools/feedback.mjs from data/site.json and delimited by <!--feedback--> markers — never typed by hand.

   It obeys rule 1: the address and the sentence are in the artifact's own language, and test/deploy.test.js fails if a page carries the other language's. It is a mailto, not a form, so it needs no script and still works from a USB stick with no connection.

   Two families are excluded, for reasons that are the same reason. The wall chart is a fixed-height A4 sheet that crops its overflow, and one more line pushed all ten past themselves — caught by test/render-wall-chart.js. The three generated desk cards have no footer at all: tools/cards.mjs rewrites them whole, so anything injected would be erased on its next run. Every other fixed-sheet artifact was measured before being left in — the worksheets, remediation sheets and parent guides all print on the same number of pages with the line as without it.

6. Grade 1–10 spine — verified against the CG

Every row below is taken from the official curriculum guide, committed at docs/research/source/. This replaces an earlier proposed spine that was assembled from search summaries and was wrong in seven of ten rows.

All ten grades are shown with their CG Quarter 1 Number and Algebra content, which is the strand this repository builds against. Grade 1's topic is verified as the earlier proposal had it; the rest changed.

CG Quarter 1 is taught in Term 1 under the three-term calendar, so this spine remains the right starting point for every grade — see §7.

Three rows changed again while the grades were being built, and for the same reason as before — the guide says something narrower than the band description suggests. Grade 5's Quarter 1 carries multiplication of fractions alongside GMDAS; Grade 8's carries factorization alongside monomials; Grade 10's quadratic inequalities extend to two variables, which is a region of the plane, not marks on a number line. Each was found by reading the competency list, not the content-standard summary.

What the verification changed

The earlier proposal assumed Number and Algebra led every Quarter 1 and guessed topics from grade-band descriptions. In reality:

• Every Quarter 1 in Grades 1–10 leads with Measurement and Geometry in the CG's own listing order. Number and Algebra follows.
• Grade 5 Q1 is not fractions — it is the GMDAS rules, plus 12- and 24-hour time.
• Grade 6 Q1 is not ratio and percent — it is the four operations with decimals.
• Grade 7 Q1 is not rational numbers on the number line — it is percentages and rates.
• Grade 8 Q1 is not linear equations — it is measures of central tendency and monomials.
• Grade 9 Q1 is not quadratic equations — it is relations and functions.
• Grade 10 Q1 is not SOH-CAH-TOA right-triangle trigonometry — it is the laws of sines and cosines for oblique triangles, and quadratic inequalities.

Lesson, and it held for all ten builds. Do not infer a grade's content from its band or from what "usually" comes at that level. Open the CG. Every one of the seven errors above came from a plausible-sounding assumption, and three more were caught the same way later.

Placement within a term

The CG assigns content to quarters, not weeks, and it predates the three-term calendar entirely. Two separate mappings are therefore this repository's own, not DepEd's:

1. Which term a CG quarter falls in. Four quarters into three terms means terms straddle quarter boundaries. The Grade 4 syllabus §5 sets out the distribution and the reasoning.
2. Which week within that term. Nine of the ten sets sit at Term 1 Week 7, derived from the CG's listing order; Grade 1 sits at Week 9. Grade 4's placement is corroborated by published Grade 4 Term 1 Week 7 material; the others are not.

A school's approved budget of work may differ on both counts. Obtaining a grade's Budget of Work removes the guesswork — see source-catalogue.md.

7. What the ten builds settled

All ten grades are built. What follows is what the template could not absorb unchanged, kept here because the same pressures will apply to any further learning area.

The visual system does not generalise; the structure does. "Ten Times" is place-value specific, so Grade 1 needed its own (DESIGN-WHOLE-AND-PARTS.md). Everything structural — the artifact spine, the Lesson Exemplar headings, the three-term syllabus, the offline-first constraint — carried over to all ten without amendment.

Language is a key-stage rule, not a per-grade choice. Grades 1–3 are wholly Filipino under MTB-MLE, which makes every CG competency a translation rather than a quotation, and requires an English reading copy of the five teacher documents and of none of the four learner-facing artifacts. Grade 3 is the last MTB-MLE year. The rule is asserted per key stage in the test suite so a new grade cannot opt out by omission.

Grading splits three ways, and one way is a gap. Grade 1 is descriptive and ships no class record. Grades 4–10 use 20/50/30. Grades 2 and 3 are still numerically graded but the Key Stage 1 weights are not held here, so their class records take teacher-entered percentages and refuse to grade until the three sum to 100. Inventing a plausible weighting would have been the easy move and the wrong one.

Three engines, and copying one is where the bugs came from. The Key Stage 1 game engine, the Grade 4 original, and the shared Key Stage 2/3 engine. Two shipped crashes came from copying an engine and leaving a literal behind that named the source grade's data. Both are now derived from the round table rather than repeated, and test/browser-all.test.js plays every game to the teacher panel so the next one cannot ship silently.

8. What the second learning area settled

Science, Grades 3–10, is built. Written after it shipped; the reasoning is in science-spine.md §7.

Generate the structure, hand-write the prose. §7 above names copied game engines as the source of two shipped crashes. Rather than copy a folder eight times, tools/science.mjs emits all eight structural artifacts per grade from data/science/gNN.json — so the whole learning area shares one game engine, one slide runner and one class record, and no grade carries a literal it could fail to edit. The five markdown documents per grade stayed hand-written on purpose: generating prose from data only moves the prose into the data file and loses the diff.

A grade number is not a key. The largest piece of unplanned work in the Science build had nothing to do with Science. The grade number was silently the key in the inventory's cell map, in the short-URL redirect table, in the gallery's lookups and in five test assertions written as constants — and every one of them broke or silently merged the moment two directories shared a grade. All are now keyed on the directory slug or derived from data/grades.json.

A learning area can bring its own assessment shape. Mathematics syllabi propose their own performance tasks. The Science guide requires one per quarter (page 17) and supplies them — between one and three per quarter, so eight tasks in Grade 9 and seven in Grade 10. Every Science assessment pack carries a rubric for every task the guide gives, names which one the syllabus placed in the performance-task week, and says why. Do not assume the next area's assessment structure matches either of these two.

Expect a new visual system, and budget for it. §7 predicted this and it held. Science needed DESIGN-FOUR-DOMAINS.md — four domain hues, each also glyphed and hatched so the coding survives monochrome printing, and one structural element Mathematics has no use for: two equal boxes, what I saw and what I think it means, on every learner worksheet.

9. The 33-week planner, and what "covered" means

tools/weeks.mjs emits week-planner.html per grade: all 33 weeks on one page, each carrying its focus line, its CG reference and the verbatim competency text, plus a per-quarter band with the content standards, the performance standard and the performance task. Every string is lifted from the committed syllabus — the tool invents nothing, and a week with no built artifacts says so.

It exists because the syllabus already had both halves and kept them apart. §5 says Week 12 — Q2 · 4–5; §4 says what those competencies are, three screens earlier. Joining them is the whole feature.

The coverage claim is now checked. Each syllabus ends with a hand-written table asserting every competency is placed exactly once. Nothing verified that until this tool parsed both halves; --check now fails the build if a competency is dropped, taught twice, or cited by a reference that does not resolve. First run across all eighteen grades: 594 weeks, 830 competencies, all placed exactly once — the prose was right.

Two area differences it surfaced. Mathematics puts the performance task in the unnumbered end-of-term block; Science gives it a numbered week — so the PT filter is shown only where it can match. And Mathematics quarters are not domains, so only the Science planners colour-code by quarter; doing it for Mathematics would imply a category that is not there.

What the planner does and does not mean

It covers all 33 weeks in the sense the sources support: every week is placed, named, and carries its verbatim curriculum content. It does not mean 33 weeks of teaching materials. Lesson plans, slides, games and worksheets still exist for one week per grade. Building them for the other 32 would mean inventing misconceptions, day plans and activities with no source to check them against — the failure this repository is organised to avoid. The planner marks the built week and labels every other week honestly.

Still open

• Teaching materials are one week per grade, in both learning areas. The planner covers all 33 weeks as curriculum; everything outside the built week is a competency with no lesson behind it.
• The Filipino copies for Grades 1–3 Mathematics and Grade 3 Science need a Filipino-speaking teacher's review.
• No artifact has been used with real learners.
• The Budget of Work for any grade would replace this repository's week-placement guesswork — see source-catalogue.md.
• Eight curriculum guides remain unheld. English is the next one wanted; the URLs are in data/learning-areas.json under documents.wanted[].urls.