Zahlenkette: Number Learning App for Preschoolers

Zahlenkette: Number Learning App for Preschoolers — Product Specification #

Version: 1.0 · Platform: native iPhone and iPad app (iOS/iPadOS 17.0+) · Language: German first · Status: final, ready for execution

Overview #

Zahlenkette (working title) is a German-first iPhone and iPad app that teaches children aged 2–6 the numbers 1–20 through 12 short, playful mini-games. It is built on German early-math didactics — the Zwanzigerfeld, red/blue groups of five, the Kraft der Fünf, structured quantities before scattered ones, Zahlzerlegung and the number line — and shows every number as three linked representations: numeral, word and quantity. Children who cannot read yet play alone: every instruction is spoken and every child-facing control is a picture or a numeral. An adaptive learning engine tracks mastery per skill and per number and picks the next tasks from each child's weak spots with spaced repetition. A gentle reward system (stars, a personal garden, 20 Zahlenfreunde characters, a sticker album and a daily five-minute Abenteuer) makes progress visible without dark patterns. Parents manage up to five child profiles, progress, time limits and settings in a parent area behind a parental gate, where a StoreKit 2 subscription with Family Sharing unlocks eight premium games; four games stay free forever. V1 runs fully offline with no backend, no third-party SDKs and no data collection; iCloud sync follows in V1.1.

This document is the complete build specification. It is written so that an AI coding agent or a developer can execute it without clarifying questions: every concern has one owning section, other sections reference it by number, and every open choice has a recorded default.

Table of Contents #

• 1. Before You Start
• 2. Product Overview and Goals
• 3. Personas and User Journeys
• 4. Didactic Foundation
• 5. Technology Stack and Architecture
• 6. Conventions and Coding Standards
• 7. Data Model and Persistence
• 8. Content System and Data Files
• 9. Adaptive Learning Engine
• 10. Shared Game Framework
• 11. Game Specifications: Free Games
• 12. Game Specifications: Premium Games I
• 13. Game Specifications: Premium Games II
• 14. Reward Economy and Gamification
• 15. Child Profiles and Session Management
• 16. Parent Area and Parental Gate
• 17. Monetization and Subscriptions
• 18. Screen Inventory and Navigation
• 19. Design System and Accessibility
• 20. Audio, Voice and Localization
• 21. Content and Audio Inventory
• 22. Store Listing and Parent-Facing Copy
• 23. Privacy, Security and App Store Compliance
• 24. Performance, Offline and Reliability
• 25. Testing and Quality Assurance
• 26. Release Scope: V1, V1.1 and V2
• 27. Milestones and Execution Plan
• 28. Risks and Decisions to Revisit
• 29. Executor Instructions
• 30. Glossary

1. Before You Start #

This section lists every real-world decision that lies outside the code but affects the build, the App Store submission or the launch. Each decision has a default. The executor never blocks on an unanswered question: if the product owner has not answered by the time the decision is needed, the default applies, the executor records it in DECISIONS.md at the repository root (entry format in Section 6.12.1, usage in Section 1.4), and work continues.

1.1 How to read this document #

1.1.1 Section ownership model #

Every concern has exactly one owning section. The owning section is the single source of truth for that concern's values, rules and edge cases. Other sections may mention an owned value only when they need it for context, and then they state it identically and cite the owner (for example "the daily time limit defaults to 20 minutes, see Section 15"). If two sections ever appear to disagree, the owning section wins and the discrepancy is a documentation defect to be logged in DECISIONS.md.

1.1.2 Conventions used throughout #

1.1.3 Language #

The specification prose is English. Every child-facing and parent-facing string, every spoken line, every game name and every German didactic term is German and appears in German in this document. V1 ships German only; the localization structure is ready for English from day one (Section 20).

1.2 Decisions with defaults #

Each row is a question the executor may put to the product owner. If there is no answer at the moment the decision is needed, the default in the fourth column applies. "Needed by" refers to the milestones in Section 27.

1.3 What is not a question #

The following are fixed and must not be reopened by the executor. They are listed so nobody spends time on them.

1.4 Format of DECISIONS.md #

DECISIONS.md has exactly one entry format, defined in Section 6.12.1 (entry layout, log ID scheme and the complete list of allowed statuses). Entries are appended and never edited in place. This section only fixes how the questions of Section 1.2 are logged:

• Every default applied from the table in Section 1.2 gets its own entry. The entry names the question ID of Section 1.2 (for example "1.2 D-15") in its references, so the log ID of Section 6.12.1 and the question ID of Section 1.2 are never confused.
• The status of such an entry is default applied (no answer by the "Needed by" milestone) or answered by product owner. A later change of the value is a new entry with status revisited that references the earlier one.
• A discrepancy found between two sections is logged with status spec discrepancy; the entry names both sections and states which owning section was followed (Section 1.1.1).

1.5 Scope at a glance #

The binding release scope, including the launch checklist, is in Section 26. This table is an orientation only.

2. Product Overview and Goals #

2.1 Vision #

Zahlenkette (working title, see Section 1.2 D-03) is a calm, German-first iPhone and iPad app in which children aged 2 to 6 build solid number sense for the numbers 1 to 20 through twelve short mini-games. Children play alone, without being able to read: every instruction is spoken, every child-facing control is a picture or a numeral. Every number is always met in three linked forms (numeral, word, quantity) and in the structures German early-math didactics relies on: groups of five, the Zwanzigerfeld, the bead chain and the number line (Section 4). An adaptive engine keeps every child in the zone where most tasks succeed on the first try (Section 9). Parents see honest progress per number and skill in a gated parent area (Section 16), without ads, tracking or manipulation.

The one-sentence promise to parents: Ihr Kind lernt die Zahlen bis 20 so, wie es auch in Kita und Grundschule gelernt wird: in Fünferschritten, ohne Druck, ohne Werbung.

2.2 Problem #

2.3 Market #

2.3.1 Launch markets #

Germany, Austria and Switzerland (App Store storefronts DE, AT, CH), German language only. Other storefronts follow with English content in V1.2 (Section 26).

For sizing orientation only (not a requirement): annual births in Germany have been roughly 680,000 to 800,000 in recent years, so roughly 3.5 to 4 million children aged 2 to 6 live in Germany; Austria and German-speaking Switzerland add several hundred thousand more. The addressable group is the subset of families with an iPhone or iPad who allow some screen time for learning.

2.3.2 Market-specific notes #

2.4 Product principles #

These principles decide every open design question. When a requirement anywhere in this document seems to allow two readings, choose the reading that better satisfies these principles, in this order.

2.5 Goals and success criteria #

2.5.1 Goals #

2.5.2 Measurement constraints #

The app contains no analytics and makes no network calls of its own (Section 23). Every success criterion is therefore measured with exactly these sources and no others:

Decision: the app never adds a feedback form, survey prompt, rating nag or any other mechanism that transmits data. The only in-app rating mechanism allowed is Apple's system review request, shown only inside the parent area (Section 16 owns when and whether it appears); it is never shown in the child area.

2.5.3 Success criteria #

Decision: SC8, SC9, SC10 and SC11 are business health indicators, not release gates. SC1, SC3, SC6, SC7, SC12 and SC13 are release gates for V1 (Section 26). SC2, SC4 and SC5 are strong signals: if missed, the gap and the planned correction are recorded in Section 28's register, but launch is not blocked.

2.5.4 Reaction to missed targets #

2.6 Non-goals #

The following are explicitly out of scope for V1. Section 26 owns the release scope and says which of them come later.

2.7 Product at a glance #

2.7.1 The twelve games #

Each game has exactly three difficulty steps in V1: step1 ("Leicht"), step2 ("Mittel"), step3 ("Schwer"). The primary skill is credited with weight 1.0 and the secondary skill with weight 0.5 per task (Section 9).

Entdecken's free-explore mode records no mastery and gives no stars; only its "Zähl mit" mode does (Section 11). Entdecken is never part of a daily Abenteuer; without a subscription the Abenteuer draws from the three Abenteuer-eligible free games Wie viele?, Hör hin and Was fehlt? (Sections 8.8.1, 9.16.2).

2.7.2 Product building blocks #

3. Personas and User Journeys #

This section describes who uses the app and walks through every important path step by step. Journeys use the screen IDs S-01 to S-27; Section 18 owns the screen list, the elements on each screen and the navigation map. Where a journey step depends on a rule owned by another section, the rule is cited, not redefined.

3.1 Personas #

The app has two user groups: children (primary users, cannot read) and parents (set up, pay, follow progress). The five personas below are used in journeys, test scenarios (Section 25) and design reviews.

3.1.1 Persona overview #

3.1.2 Mila (3;4), "Die Kleinen" #

• Situation: Goes to Kita. Can recite "eins, zwei, drei, vier, fünf" but skips or double-counts objects beyond four. Recognizes "her" numeral 3 because she is three.
• Behavior with the app: Taps quickly and repeatedly, often before the instruction has finished. Loses interest after 3 to 4 minutes. Loves the garden and animals. Cannot read at all. Holds the iPad flat on her lap.
• Needs: Short rounds (4 tasks per round for her level, Section 9). Big targets (at least 60 x 60 pt, Section 19). Instructions that are short and are repeated when she taps the speaker button. Tolerance for accidental taps. Immediate, gentle feedback.
• Frustrations to avoid: Anything that looks like a failure, loud sounds, waiting, a screen that does not react to her taps, being thrown out of the game by an accidental tap on a navigation control.
• Design implications: Taps during a spoken instruction are accepted as answers only once the task's answer controls are enabled (Section 10); accidental exits from a round are prevented as specified in Section 10; quantities stay within 1 to 5 until the engine widens her range (Section 9); decomposition tasks for her level use only the numbers 2 to 5 (Section 4.7).

3.1.3 Jonas (5;8), "Vorschule" #

• Situation: Last Kita year ("Vorschulkind"). Counts to 20, but unsure at "dreizehn, vierzehn", occasionally says "einszehn". Recognizes numerals 1 to 10, confuses 12 and 21 when he sees them (he has seen 21 on a house number). Mirrors 3 and 7 when writing.
• Behavior: Wants to be good; is annoyed by tasks he finds "Babykram". Plays 6 to 8 minutes. Uses the Apple Pencil his mother bought for her own use when he finds it on the table.
• Color vision: Red-green color vision deficiency (deuteranomaly). The red and blue beads look similar to him in brightness. The shape rule (solid bead for the first five, "Lochperle" with a white center ring for the second five, larger gap between groups of five, Section 4.4 and Section 19) lets him see the structure without relying on hue.
• Needs: Rising challenge (difficulty stepping, Section 9), widening to 1 to 20, games with a visible goal (Punkt zu Punkt picture, Zahlenfreunde), writing practice with correct stroke order.
• Frustrations to avoid: Repetition of mastered items without variation, being treated like his little sister, losing Zahlenfreunde he has already befriended.
• Design implications: Separate profile with its own level and range; the engine's task mix includes 10% stretch tasks (Section 9); befriended friends are never lost (Section 14).

3.1.4 Lena (4;6), "Vorschule" on an iPhone SE #

• Situation: Only child in Graz. Counts to 10 reliably, recognizes numerals 1 to 5 and some up to 10. Knows the dice patterns from board games.
• Behavior: Plays alone on the sofa while her father is in the kitchen and cannot help immediately. Small screen, held in both hands, often in landscape.
• Needs: Everything must fit and remain tappable on 375 x 667 pt in both orientations (Section 19). Everything must work with the phone muted: the app plays voice even when the Ring/Silent switch is set to silent, as specified in Section 20; if system volume is zero, the visual path still carries every task (Section 20).
• Design implications: Lena is the reference child for success criterion SC1 (a 4-year-old completes a session unaided, Section 2.5.3). The iPhone SE is the reference device for layout acceptance (Section 25).

3.1.5 Sarah (36), parent of Mila and Jonas #

• Situation: Pharmacist, works part-time. One family iPad shared by both children. Reads app privacy labels before installing. Uses the iPad's Screen Time for overall limits but likes per-child limits inside the app.
• Goals: Both children practice numbers calmly; she knows what each child can do; no ads, no data collection, no child accounts; the children cannot buy anything.
• Frustrations: Apps that nag children to ask parents for purchases; streaks that cause tears; dashboards full of meaningless points.
• Behavior in the app: Sets up Mila first, adds Jonas later in the parent area. Checks progress once or twice a week in the evening, for 2 to 3 minutes. Adjusts Jonas's range manually to 1 to 20 when his Kita teacher says he is ready.
• Design implications: Profile picker by avatar only (S-04); per-profile time limits (Section 15); parental gate before every parent function (Section 16); "Gerade schwierig" in plain German (Section 16); data export and deletion (S-23).

3.1.6 Thomas (41), parent of Lena #

• Situation: Engineer in Graz. iPhone SE, no iPad. Distrusts subscriptions after being caught by a hard-to-cancel one. Pays for apps that respect his family.
• Goals: Try the free games first; understand exactly what he pays and when; cancel easily; keep what Lena earned if he cancels.
• Behavior: Plays the free games with Lena for a week, then starts the 7-day trial of the yearly plan in the parent area. Cancels once to test, then resubscribes months later.
• Design implications: Four games free forever with all three steps (Section 17); transparent paywall with price, trial end and cancellation note (Section 22); "Abo verwalten" opens Apple's subscription management (Section 17); after a lapse nothing earned is lost (Section 17, journey J-07).

3.2 Journey notation #

• Each journey has an ID (J-01 to J-11), a primary persona, a precondition, numbered steps, and edge and failure paths.
• A step names the screen (S-xx), what the user does, what the app does, and what is persisted.
• "Spoken:" marks a line the voice speaks. The German text of a line is owned by the section that specifies the behaviour (Sections 11 to 13 for game lines; Sections 14, 15 and 17 for reward, session and lock lines), and Section 21 lists every line with its audio ID, mirroring those texts exactly. Lines quoted here are copies for orientation; the owning section wins.
• Timings are typical values for orientation, not requirements, unless a section is cited.

3.3 J-01 First launch #

Persona: Sarah sets up Mila. Precondition: App freshly installed; no profile exists.

Edge and failure paths:

3.4 J-02 Daily session (child alone) #

Persona: Lena on the iPhone SE. Precondition: One profile (Lena), time limit 20 minutes, not yet reached today; today's Abenteuer already done.

Edge and failure paths:

3.5 J-03 Daily Abenteuer #

Persona: Jonas. Precondition: Jonas's profile; today's Abenteuer not yet completed; family has an active subscription.

Edge and failure paths:

3.6 J-04 Parent check-in #

Persona: Sarah, in the evening. Precondition: Two profiles (Mila, Jonas); both played this week.

Edge and failure paths:

3.7 J-05 Free user taps a locked game #

Persona: Lena. Precondition: No subscription.

Edge and failure paths:

3.8 J-06 Parent subscribes (trial) #

Persona: Thomas. Precondition: Parent area opened through the gate (from S-15 or from S-18); never subscribed before; online.

Edge and failure paths:

3.9 J-07 Subscription lapses #

Persona: Thomas and Lena. Precondition: Thomas cancelled during the trial or later; the paid period (and any billing grace period configured per Section 17) has ended.

Edge and failure paths:

3.10 J-08 Time limit reached #

Persona: Mila. Precondition: Mila's time limit is 20 minutes; she has played 19 minutes and 40 seconds today.

Edge and failure paths:

3.11 J-09 Sibling switching and adding a profile #

Persona: Sarah, Mila and Jonas on one iPad.

Adding the second profile:

Switching:

Edge and failure paths:

3.12 J-10 Device offline #

Precondition: Airplane mode (for example on a flight), subscription active.

3.13 J-11 App interrupted #

Precondition: A child is in S-07 in the middle of a task.

3.14 Screen coverage by journey #

Every screen appears in at least one journey. Section 25 derives UI test scenarios from this matrix.

4. Didactic Foundation #

This section explains the didactic approach and turns it into testable rules. Rules carry IDs (DR-01 and following) so that game sections, design reviews and tests can cite them. The didactic rules are binding for every game, every visual and every spoken line. Section 9 owns all numeric thresholds of the learning engine; Section 10 owns the mechanics of hints and feedback; Sections 11 to 13 implement the rules in each game; Section 19 owns the visual dimensions.

4.1 Background and sources #

The app follows the mainstream of German-language early-mathematics didactics as used in Kita and the first school year. The approach is informed by, among others:

• Erich Ch. Wittmann and Gerhard N. Müller, "Das Zahlenbuch" (textbook series and accompanying materials): structured number representations, Zwanzigerfeld, Zwanzigerreihe, emphasis on the "Kraft der Fünf" and on active, discovery-based learning.
• Michael Gaidoschik, publications on preventing arithmetic difficulties ("Rechenschwäche vorbeugen" and related work): moving children from counting one by one to structure-based strategies, the role of the five and ten structure, finger patterns used as structured images.
• Günter Krauthausen, "Einführung in die Mathematikdidaktik" and work on representations and Arbeitsmittel: careful, consistent use of a small set of representations.
• Kristin Krajewski and colleagues, the model of the development of number-quantity competence and the preschool program "Mengen, zählen, Zahlen": from number words and quantities without link, to linking number words with exact quantities, to understanding relations between numbers (part-whole, differences).
• Rochel Gelman and C. R. Gallistel, "The Child's Understanding of Number": the five counting principles (Section 4.9).
• Jerome Bruner's distinction of enactive, iconic and symbolic representation (enaktiv, ikonisch, symbolisch): the app lets children act (drag, trace, shake), see images (structured quantities) and use symbols (numerals, words).

No quotations from these works appear in the app or in marketing texts. Parent-facing copy may mention that the app "follows the approach used in German Kita and Grundschule" (Section 22); it does not claim endorsement by any author or institution.

4.2 Three linked representations #

Every number exists in three representations, and the child learns the links between them:

Terminology used in this document: a "Ziffer" is one of the symbols 0 to 9; a number from 10 to 20 is written with two Ziffern. "Numeral" in this document means the complete written number (for example "14").

4.2.1 Rules #

4.2.2 Representation pairs per game #

Each game trains specific links between representations. Section 11 to 13 own the mechanics; this table fixes the didactic pairing that the mechanics must respect.

4.3 Kraft der Fünf (the power of five) #

Children should see 7 as "five and two" at a glance instead of counting seven single objects. The five is the natural first unit (one hand) and the ten is the second (two hands). Every structured representation in the app is built on this.

4.4 Zwanzigerfeld, bead chain and Rechenrahmen colors #

The app uses three structured layouts. All three follow the same color and shape logic, taken from the Rechenrahmen (school abacus with two rows of ten beads, each row five red and five blue).

4.4.1 Color and shape logic #

4.4.2 Zwanzigerfeld layout #

The Zwanzigerfeld is a field of 2 rows x 10 places. Each row is split into two groups of five by a vertical gap (DR-15). Row 1 holds 1 to 10, row 2 holds 11 to 20. A quantity n fills the first n places in reading order: row 1 from left to right, then row 2 from left to right. This is the standard ("wide") arrangement; the compact arrangement for interactive fields in narrow windows is defined in DR-20.

Row 1:  (1)(2)(3)(4)(5)   [6][7][8][9][10]
Row 2:  (11)(12)(13)(14)(15)   [16][17][18][19][20]

( ) = red solid bead      [ ] = blue Lochperle
Example 13: row 1 full (5 red + 5 blue), row 2: 3 red, remaining 7 places empty outlines.

The place-to-coding mapping is a pure function. Reference logic (the concrete type lives where Section 5 places shared domain logic; Section 19 turns it into geometry):

/// Didactic coding of one place in a structured field (Section 4.4).
public struct StructuredPlace: Equatable, Sendable {
    public let index: Int        // 1...20, position within the set
    public let row: Int          // 0 for 1...10, 1 for 11...20
    public let column: Int       // 0...9 within the row
    public let fiveGroup: Int    // 0 or 1 within the row (column / 5)
    public let isFirstFive: Bool // true -> red solid bead, false -> blue Lochperle

    /// Returns nil outside 1...20 (no trapping; Section 6 forbids precondition in production code).
    public init?(index: Int) {
        guard (1...20).contains(index) else { return nil }
        self.index = index
        self.row = (index - 1) / 10
        self.column = (index - 1) % 10
        self.fiveGroup = self.column / 5
        self.isFirstFive = self.fiveGroup == 0
    }
}

4.4.3 Bead chain (Zahlenkette) #

The bead chain is a linear string of 20 beads coded per DR-14 (red 1 to 5, blue 6 to 10, red 11 to 15, blue 16 to 20) with the group gap of DR-15. It shows order (Was fehlt?) and is the app's namesake.

4.4.4 Rechenrahmen #

V1 has no separate Rechenrahmen game. The Rechenrahmen contributes the color logic (DR-14) and the convention that counted beads sit on the left and uncounted places on the right (DR-18 empty outlines take the role of the unpushed beads).

4.5 Structured before scattered #

Children first learn to read quantities in the standard structure, then in other familiar patterns, and only then in arrangements without structure. Arrangements are classified as follows:

4.6 Subitizing (Simultanerfassung) #

Subitizing is recognizing a quantity at a glance without counting. Perceptual subitizing of unstructured dots is limited to very small quantities (for young children about 3, for older preschoolers and adults about 4). Conceptual or quasi-simultaneous recognition uses structure: 7 is seen as 5 and 2, 14 as 10 and 4. Blitzblick and parts of other games train this.

DR-26 Subitizing limits. Tasks where a quantity is displayed only for a moment (flash tasks) respect these maximum quantities:

4.7 Zahlzerlegung (decomposition) #

Decomposing a number into parts (7 = 3 + 4) is the foundation of later adding and subtracting and of the part-whole concept. The Schüttelbox is the classic Vorschule material: a box with N beads and a divider; after shaking, the beads land on the two sides and the child states the split.

4.8 Number line (Zahlenweg) #

Froschsprung uses a number line as a path of stepping stones: a linear, ordinal model of the numbers, where "more" is further along and "less" is further back.

4.9 Counting principles #

The five counting principles (Zählprinzipien) describe what a child must understand to count correctly. The app addresses each explicitly.

4.10 German number words 1 to 20 #

The voice pronounces number words in neutral Hochdeutsch (Section 1.2 D-10). The audio IDs follow the convention of Section 20: num.<n> for the statement form and num.<n>.q for the question intonation; Section 21 lists every file.

The "Structure" column is the split label (DR-09) and the spoken decomposition (DR-43): for 11 to 19 it is always "10 + (n − 10)", spoken "zehn und (n − 10)" (for example "zehn und sieben" for 17), never "zehn und fünf und zwei". Inside the second ten the image still shows five-first (DR-08), so 17 is drawn as a full ten, five red and two blue; that rendering structure never becomes a spoken or written label.

4.10.1 Modeling the teens as 10 + n #

German teen words name the ones before the ten ("vier-zehn" = four-ten), while the numeral writes the ten first ("14"). This inversion is a known source of errors (a child hears "vier" first and writes or picks 4, or writes "41").

4.10.2 The number 0 #

Decision: V1 trains the numbers 1 to 20. Zero ("null") is not a target number, has no mastery record and is never the required answer of a task. The number line's start position represents zero without a label and is never named (DR-36). The word "null" is recorded once (num.0, statement form only, declared as the optional zero entry of numbers.json, Section 8.6) and is used only where a child writes the Ziffer 0 as part of 10 or 20 in Nachspuren (Section 12.4).

4.11 Skill taxonomy #

Eight skills are tracked per number 1 to 20 (Section 9 owns the mastery math). A task credits its primary skill with weight 1.0 and its secondary skill with weight 0.5 (Section 9). The raw values are those of enum Skill: String (Section 5, Section 7).

Notes:

• Entdecken's free-explore mode records no mastery; only "Zähl mit" credits name (primary) and recognize (secondary) (Section 11).
• Which number a task credits (for example both numbers in a comparison, the whole in a decomposition) is defined per game in Sections 11 to 13 and in the task model of Section 10; DR-33 fixes the decomposition case.
• Cells that are not applicable (the number 1 for decompose; numbers above 5 for decompose at littleOnes; numbers 11 to 20 for decompose at both levels in V1, DR-30) are never practiced for that level and are shown as not applicable in the parent area (Section 16). Section 9.4 applies the same ranges.

4.12 Levels and range stages #

4.12.1 Levels #

The level (enum Level: String) sets starting range, round length, active skills and permitted content. The level is chosen by the parent in S-03 or S-20; age is guidance only, because the app stores no birthdate.

4.12.2 Range stages #

Widening moves to the next stage when the child is ready; narrowing returns to the previous stage when newly added numbers prove too hard. Section 9 owns the exact conditions (thresholds, minimum sessions, re-attempt delay) and the parent override that disables automatic range changes.

4.13 Error philosophy #

Errors are information about the child's current strategy, not failures. The app responds to an error the way a good Kita teacher would: calmly, with a smaller next step, and by showing the structure. Section 10 owns the hint ladder mechanics (attempt counting, which visual changes happen, timing); Section 14 owns the rule that every completed task, including a shown solution, earns its star. This section fixes the didactic intent the mechanics must serve.

4.13.1 The hint ladder, didactically #

4.13.2 Rules #

4.13.3 Typical errors and the app's didactic response #

4.14 Didactic acceptance checks #

Section 25 turns these into test cases. A build fails didactic acceptance if any check fails.

5. Technology Stack and Architecture #

This section is the only place in the document where tool, language and SDK versions are stated. Every other section refers to "the toolchain in Section 5" instead of naming a version.

5.1 Versions and Toolchain #

These version lines are a known-good floor, not a lockfile. At build time, install the current stable release of each dependency (npm install <pkg>@latest, or your ecosystem's equivalent), confirm the major line still matches, and let the lockfile record the exact resolved versions.

5.1.1 How the version rule applies to this project #

• The project has zero third-party packages. There is no Package.resolved with external pins, and none may ever be added (see 5.2.2 and Section 29).
• The rule above therefore applies to Xcode, the Swift toolchain and the iOS SDK. At the start of work and before each release build:
  1. Install the current stable Xcode of the 27.x line (or, if a newer major line is current, stay on 27.x until a DECISIONS.md entry approves the move after a full test pass).
  2. Confirm xcrun swift --version reports a Swift 6.x toolchain and that the project still compiles in Swift 6 language mode with zero warnings.
  3. Record the exact Xcode version and build number that produced the build in the repository file .xcode-version (single line, e.g. the output of xcodebuild -version | head -1), and add a DECISIONS.md entry whenever it changes. This file is the project's equivalent of a lockfile.
• Verification step (once, milestone M0): confirm Xcode 27.x still supports an iOS 17.0 deployment target (archive a Release build and check there is no deployment-target warning), and confirm Swift Testing tests run on an iOS 17.x simulator runtime. If Swift Testing cannot run on the iOS 17.x runtime, run unit tests on the current simulator runtime only, keep iOS 17.x coverage through the XCUITest suite, and record this in DECISIONS.md.
• Install the iOS 17.x simulator runtime in addition to the current one (Xcode > Settings > Components). It is required for the minimum-OS test pass and for an "iPhone SE (3rd generation)" simulator with the 375 x 667 pt screen, which may no longer be offered with the newest runtime.

5.2 Frameworks #

5.2.1 Apple frameworks used #

Decision: no other Apple framework is linked in V1 without a DECISIONS.md entry. Section 24 decides whether MetricKit is used; if it is, it is imported only by the App target. Network (URLSession, Network) is forbidden everywhere; StoreKit's own networking is system-managed and is the only network activity of the app (Section 23 owns the enforcement check).

5.2.2 Third-party dependencies #

None. No Swift packages, CocoaPods, Carthage frameworks, binary frameworks, analytics, crash reporters, ad SDKs or font files from third parties. The system font SF Pro Rounded is used via Font.system(.body, design: .rounded) and is not bundled. A pull request that adds a dependency to Package.swift other than local targets, or adds a package reference to Zahlenkette.xcodeproj, is rejected (Section 6.12 checklist).

5.3 Module Architecture #

5.3.1 Package decision #

Decision: one local Swift package, Packages/ZahlenketteKit, with one library product per target, plus the Xcode app project Zahlenkette.xcodeproj that contains the app target (the composition root), the app-level test target and the UI test target. Rationale: one Package.swift makes the dependency graph visible and enforced in one file; separate library products let each game compile and be tested in isolation; the app project stays thin.

5.3.2 Module graph #

+---------------------------------------------------------------------+
|           Zahlenkette (app target) - composition root               |
|           links every library product listed below                  |
+---------------------------------------------------------------------+
        |                     |                         |
        v                     v                         v
+----------------+    +----------------+        +----------------+
|  Game* (x12)   |    |  ZKParentArea  |        |   ZKRewards    |
+----------------+    +----------------+        +----------------+
        |               |  |  |  |  |                  |
        v               |  |  |  |  +--> ZKLearningEngine
+----------------+      |  |  |  +-----> ZKStore        |
|   ZKGameKit    |      |  |  +--------> ZKDesignSystem |
+----------------+      |  +-----------> ZKPersistence <+
   |     |     |        +--------------> ZKCore
   |     |     +--> ZKDesignSystem
   |     +--------> ZKAudio ----> ZKContent
   +--------------> ZKContent

Every library target also depends on ZKCore (arrows omitted).
ZKLearningEngine, ZKContent, ZKPersistence and ZKStore depend on nothing except ZKCore; ZKCore depends on nothing.

Read the diagram together with the table below; the table is authoritative.

Decision: child-mode shell screens (profile picker, child home, game picker, Abenteuer flow, garden, shop, friends gallery, sticker album, ask-a-parent, time's up, break nudge, befriending celebration) live in the app target under App/ChildMode/, not in a separate package target. They compose ZKGameKit, ZKRewards, ZKPersistence and ZKDesignSystem, which only the composition root is allowed to combine.

Decision: types that cross the engine-to-game boundary are declared in ZKCore so that neither ZKLearningEngine nor ZKGameKit depends on the other. The boundary contract is RoundPlan (what one round will contain) and PlannedTask (one task in it). Section 9 specifies how they are produced (9.3.1, 9.9); Section 10 specifies how they are consumed (10.4.2). The declaration below is the only one in the code base; ZKGameKit and ZKLearningEngine use these types unchanged and declare no type with the same name:

// ZKCore/Planning/
public enum GameMode: String, Sendable, Hashable, Codable {
    case standard       // every planned round
    case freeExplore    // Entdecken free explore; never produced by the engine (Section 11)
}

public enum RoundContext: Sendable, Hashable, Codable {
    case single                         // a round started from the game picker
    case abenteuer(roundIndex: Int)     // 0...2 inside the daily Abenteuer
}

public enum SelectionReason: String, Sendable, Hashable, Codable {
    case focus, review, maintenance, stretchNumber, stretchStep, fallback
    /// Mapping onto the three-valued TaskBucket used by the framework and persistence (Section 9.3.1).
    public var bucket: TaskBucket { get }
}

public struct PlannedTask: Sendable, Hashable, Codable, Identifiable {
    public let id: UUID                 // derived deterministically from the round id (Section 9.3.1)
    public let skill: Skill             // primary skill credited by this task
    public let number: Int              // 1...20, the number the task is about
    public let bucket: TaskBucket       // .focus, .review, .stretch; always reason.bucket
    public let step: DifficultyStep     // the round step, or round step + 1 for .stretchStep
    public let reason: SelectionReason
}

public struct RoundPlan: Sendable, Hashable, Codable, Identifiable {
    public let id: UUID                 // the round ID; also the ledger sourceID of the round bonus
    public let gameID: GameID
    public let step: DifficultyStep
    public let level: Level
    public let range: RangeStage
    public let tasks: [PlannedTask]     // count: Section 9.9.2 (per level, or the step override of the game)
    public let abenteuerID: UUID?       // non-nil exactly when context is .abenteuer
    public let seed: UInt64             // task-generation seed for the framework (Section 10.4.2)
    public let isReentry: Bool          // planned in re-entry mode (Section 9.15)
    public let mode: GameMode           // .standard for every plan produced by the engine
    public let context: RoundContext
}

Everywhere the framework or the app needs "the round ID", it uses RoundPlan.id. A new field is added to this declaration (never to a copy elsewhere) and requires a DECISIONS.md entry. TaskBucket is the only bucket type; no other bucket enum exists.

5.3.3 Enforcing the graph #

1. Package.swift (5.3.4) declares exactly the "allowed direct dependencies" above. Nothing else. scripts/check-imports.sh verifies this by reading swift package dump-package and failing on any target dependency not in the table and on any remote package.
2. Xcode can sometimes resolve an import of a package module that is not a declared dependency because all package modules share one build products directory. Therefore scripts/check-imports.sh also greps every Sources/<Target>/**/*.swift file and every App/**/*.swift file for import lines and fails if a target imports a module outside its "may import" column or a framework outside its "extra Apple frameworks" column. It runs locally before every commit (scripts/lint.sh, Section 6.13) and in CI (Section 25.20). Forbidden symbols (network, notifications, tracking, @Attribute(.unique) and the other rules of Section 23.10) are checked by scripts/policy-check.swift; together these two scripts are the only dependency and policy checks (5.13).
3. @_exported import is forbidden.
4. The access level package is used for API shared between targets inside ZahlenketteKit that the app target does not need; public is used only for API the app target or another target needs across the package boundary.

5.3.4 Package manifest #

// swift-tools-version: 6.0
import PackageDescription

let gameTargets = [
    "GameEntdecken", "GameWieViele", "GameHoerHin", "GameWasFehlt",
    "GameBlitzblick", "GameMehrOderWeniger", "GameNachspuren", "GameSchuettelbox",
    "GameFroschsprung", "GameZahlenmonster", "GameMemory", "GamePunktZuPunkt",
]

let coreTargets: [(name: String, deps: [String], resources: Bool)] = [
    ("ZKCore", [], false),
    ("ZKLearningEngine", ["ZKCore"], false),
    ("ZKContent", ["ZKCore"], false),
    ("ZKPersistence", ["ZKCore"], false),
    ("ZKAudio", ["ZKCore", "ZKContent"], false),
    ("ZKDesignSystem", ["ZKCore"], true),        // Media.xcassets with color tokens and UI glyphs
    ("ZKGameKit", ["ZKCore", "ZKContent", "ZKAudio", "ZKDesignSystem"], false),
    ("ZKRewards", ["ZKCore", "ZKPersistence"], false),
    ("ZKStore", ["ZKCore"], false),
    ("ZKParentArea", ["ZKCore", "ZKPersistence", "ZKStore", "ZKDesignSystem", "ZKLearningEngine"], false),
]

var targets: [Target] = []
for t in coreTargets {
    targets.append(.target(
        name: t.name,
        dependencies: t.deps.map { .target(name: $0) },
        resources: t.resources ? [.process("Resources")] : nil
    ))
    targets.append(.testTarget(
        name: "\(t.name)Tests",
        dependencies: [.target(name: t.name), "TestSupport"],
        resources: [.copy("Fixtures")]
    ))
}
for g in gameTargets {
    targets.append(.target(name: g, dependencies: ["ZKGameKit"]))
    targets.append(.testTarget(name: "\(g)Tests", dependencies: [.target(name: g), "TestSupport"]))
}
// Shared test doubles and fixtures (FakeAudioService, FakeEntitlementService, FakeTransactionSource,
// in-memory persistence helpers, content fixtures). FixedClock and SplitMix64 are ZKCore types, not test types.
targets.append(.target(
    name: "TestSupport",
    dependencies: ["ZKCore", "ZKContent", "ZKPersistence", "ZKAudio", "ZKStore", "ZKGameKit"],
    path: "Tests/TestSupport"
))

let package = Package(
    name: "ZahlenketteKit",
    defaultLocalization: "de",
    platforms: [.iOS(.v17)],
    products: (coreTargets.map(\.name) + gameTargets).map { .library(name: $0, targets: [$0]) },
    targets: targets
)

Notes:

• TestSupport is a regular target at Packages/ZahlenketteKit/Tests/TestSupport that only test targets and the app's test targets depend on; the app target itself must never link it (checked by scripts/check-imports.sh). It is the only test-support target; its name is TestSupport everywhere.
• Test targets without fixtures omit the resources: argument; the executor removes .copy("Fixtures") for targets that have no Fixtures folder, because SwiftPM rejects a missing resource path.
• The manifest uses Swift 6 language mode by virtue of tools version 6.0. No unsafeFlags and no upcoming-feature flags are set in V1 (see 5.6.1).

5.4 Composition Root #

5.4.1 AppEnvironment #

AppEnvironment is the single dependency container. It is created once in ZahlenketteApp, owns every service, and is never a global singleton (no static let shared).

// App/Composition/AppEnvironment.swift
import CoreMotion
import SwiftUI
import ZKCore; import ZKContent; import ZKPersistence; import ZKAudio
import ZKStore; import ZKLearningEngine; import ZKRewards; import ZKGameKit

@MainActor
@Observable
final class AppEnvironment {
    let clock: any AppClock
    let continuousTime: any ContinuousTimeSource    // Section 15.12, input of TrustedDayClock
    let persistence: PersistenceController          // Section 7.10
    let profiles: any ProfileRepository             // Section 7.10
    let progress: any ProgressRepository            // Section 7.10
    let rewardStore: any RewardRepository           // Section 7.10
    let usage: any UsageRepository                  // Section 7.10
    let dataManagement: any DataManagementService   // Section 7.17-7.18
    let maintenance: any MaintenanceService         // Section 7.13, 7.19
    let deviceSettings: DeviceSettingsStore         // Section 7.9
    let content: any ContentStore                   // Section 8
    let audio: any AudioService                     // Section 20.5
    let entitlements: any EntitlementService        // Section 17.5.4
    let engine: any LearningEngine                  // Section 9
    let rewards: any RewardService                  // Section 14.12
    let games: GameRegistry                         // 5.4.3
    let roundResults: RoundResultCoordinator        // 5.4.5
    let lifecycle: LifecycleCoordinator             // 5.7
    let router: AppRouter                           // Section 18
    let motion: CMMotionManager                     // the single app-wide instance (5.6.1), injected into Schüttelbox

    /// Production wiring. Never throws: every failure has a fallback (5.4.4).
    /// `entitlements` is created and started earlier, in ZahlenketteApp.init (5.4.4 step 8), and passed in.
    static func live(entitlements: any EntitlementService,
                     arguments: LaunchArguments = .current) async -> AppEnvironment
    /// In-memory store, fixed clock (2026-10-01 09:00 local), fake audio, premium on. For #Preview only.
    static func preview(profiles: PreviewProfileSet = .twoChildren) -> AppEnvironment
}

Injection into SwiftUI: the root view receives AppEnvironment via .environment(appEnvironment); in addition every service is placed into EnvironmentValues under its own key so that package views (which cannot see AppEnvironment) read services with @Environment(\.audioService) and so on (Section 6.6).

Defaults exist only to satisfy the compiler and previews; production code always injects. Every default logs Logger.fault once when used in a Debug build.

Implementation note for Swift 6: an @Entry default value must be constructible from a nonisolated context. The service protocols are @MainActor class-bound protocols declared by their owning sections (5.4.2); their stub implementations declare a nonisolated init(). Verification step: if the compiler rejects a stub default, declare that entry as an optional ((any AudioService)? = nil) and expose a non-optional accessor in the declaring module that falls back to the stub; record the variant used in DECISIONS.md.

5.4.2 Service protocols #

AppClock and GameRegistry are owned here and declared in full below. Every other service protocol is declared exactly once, by its owning section, and is only referenced here with the members the composition root, LifecycleCoordinator and RoundResultCoordinator call. If a member listed here is missing from the owner's declaration, the owner's section is completed; no second declaration is written.

// ZKCore — owned by this section
public protocol AppClock: Sendable {
    /// Current wall-clock instant.
    var now: Date { get }
    /// Gregorian calendar with timeZone = .autoupdatingCurrent. Local dates are always
    /// Gregorian even if the device uses another calendar system.
    var calendar: Calendar { get }
}

public extension AppClock {
    var today: LocalDate { LocalDate(date: now, calendar: calendar) }
    func localDate(for date: Date) -> LocalDate { LocalDate(date: date, calendar: calendar) }
    func startOfDay(for date: Date) -> Date { calendar.startOfDay(for: date) }
    func startOfDay(_ day: LocalDate) -> Date      // 00:00 local of that day
}

/// A calendar day in the device's current time zone, serialized as "yyyy-MM-dd".
public struct LocalDate: Hashable, Comparable, Codable, Sendable, CustomStringConvertible {
    public let year: Int, month: Int, day: Int
    public init(date: Date, calendar: Calendar)
    public init?(string: String)                     // strict "yyyy-MM-dd", nil otherwise
    public var string: String { get }                // zero-padded "2026-10-01"
    public func adding(days: Int, calendar: Calendar) -> LocalDate
}

public struct SystemClock: AppClock { public init() }
public struct FixedClock: AppClock { public init(now: Date, timeZone: TimeZone) }   // unit tests, previews

/// Developer-menu time travel (5.10.2) and `-uiTestFixedNow` (5.9). The offset is applied on top of
/// the system clock, so time keeps advancing from the shifted instant.
/// Compiled in every configuration (package targets cannot see the app's compilation conditions,
/// 5.8.1); only the app target creates it, and only under `#if DEBUG || UITEST_HOOKS`.
public final class AdjustableClock: AppClock {        // Sendable: only immutable lets + a lock
    public init(base: any AppClock = SystemClock())
    public var offset: TimeInterval { get }           // read under OSAllocatedUnfairLock
    public func setOffset(_ seconds: TimeInterval)
    public func reset()
}

TrustedDayClock and ContinuousTimeSource (ZKCore, Time/TrustedDayClock.swift) are specified in Section 15.12. The production ContinuousTimeSource reads mach_continuous_time() converted with mach_timebase_info (sleep-inclusive, restarts at 0 after a reboot). TrustedDayClock combines that value with AppClock.now and a persisted anchor (UserDefaults key zk.clock.trustedAnchor, Section 7.9.2, read and written by the app target through DeviceSettingsStore and passed in as a value) to derive the trusted local date used for the daily time limit.

// ZKContent — excerpt only; Section 8.15 holds the declaration
public protocol ContentStore: Sendable {
    var catalog: ContentCatalog { get }                        // immutable, Sendable
    var validationReport: ContentValidationReport { get }      // shown in the developer menu
    func isGameAvailable(_ id: GameID) -> Bool                 // false if its config is invalid
}
public enum ContentLoader {
    public static func load(baseURL: URL, localeIdentifier: String) async -> any ContentStore
}

Audio (ZKAudio, declared in Section 20.5). The protocol is named AudioService; its production class is LiveAudioService, the test double in TestSupport is FakeAudioService, and the environment default is SilentAudioService (5.4.1). Its event type is AudioEvent. AudioID is a ZKCore type (5.3.2), not a ZKAudio type. Members used by the composition root and the coordinators:

Entitlements (ZKStore, declared in Section 17.5.4, which is authoritative). EntitlementService is @MainActor, class-bound and Observable; its members include state, isPremium, start(), refresh(force:) async, loadOffer(), restore(), the pending StoreKit message count, and func isUnlocked(_ tier: GameTier) -> Bool, which the child router uses for lock badges. Purchases and StoreKit message display are performed in ZKParentArea through SwiftUI's @Environment(\.purchase) and @Environment(\.displayStoreKitMessage); their results are passed into the service (Section 17.5.4), so ZKStore imports no UIKit. The production class is StoreKitEntitlementService; the environment default is LockedEntitlementService (5.4.1). start() is called in ZahlenketteApp.init (5.4.4 step 8).

// ZKLearningEngine — excerpt only; Section 9 holds the declaration (pure, Sendable, synchronous)
public protocol LearningEngine: Sendable {
    func planRound(_ request: RoundRequest, rng: inout some RandomNumberGenerator) -> RoundPlan
    func planAbenteuer(_ request: AbenteuerRequest, rng: inout some RandomNumberGenerator) -> AbenteuerPlan
    func apply(_ outcome: TaskOutcomeInput, to state: LearnerSnapshot, at now: Date) -> LearnerUpdate
}

Rewards (ZKRewards, declared in Section 14.12). The protocol is named RewardService; the production class is LiveRewardService and the test double is FakeRewardService. Every member throws RewardError (typed throws), inserts into the shared ModelContext and never saves (the caller's unit of work saves, 5.4.5). It uses the ZKCore StarReason and DecorationSize and declares neither. Members used by RoundResultCoordinator and the child shell: recordTaskCompleted(profileID:taskAttemptID:), recordRoundCompleted(profileID:roundID:), recordAbenteuerCompleted(profileID:abenteuerID:localDate:), befriend(profileID:numbers:) (numbers already computed by the engine's friend-eligibility function, Section 9), awardPictureSticker(profileID:stickerID:) for pictureCompleted events (Section 10.13.1), purchase(profileID:item:) with a DecorationOffer built by the app from ContentCatalog, place(profileID:ownedDecorationID:at:) and returnToInventory(profileID:ownedDecorationID:). Each returns the RewardEvents (or placement and purchase results) used for celebrations (Section 14.12).

// ZKPersistence — excerpt only; the single declaration of every repository is in Section 7.10.3
@MainActor public protocol ProgressRepository: AnyObject, Sendable {
    func masteryRecords(profileID: UUID) throws(PersistenceError) -> [MasteryRecord]
    func record(_ write: TaskResultWrite) throws(PersistenceError)     // no save; unit of work
    func learningState(profileID: UUID) throws(PersistenceError) -> LearningState
    func gameProgress(profileID: UUID, gameID: GameID) throws(PersistenceError) -> GameProgress
}

5.4.3 GameRegistry #

GameRegistry is declared in ZKGameKit and populated only by the app target (App/Composition/GameRegistry+All.swift). It maps each GameID to a factory producing that game's GameModule (the protocol itself is specified in Section 10). It returns any GameModule; the game container wraps the module in AnyGameModule for type erasure (Section 10.2). No other registry type exists.

// ZKGameKit
@MainActor
public final class GameRegistry {
    public typealias Factory = @MainActor () -> any GameModule

    public init()
    /// Registers a factory. Registering the same GameID twice is a programmer error:
    /// assertionFailure in Debug, the second registration is ignored in Release.
    public func register(_ id: GameID, factory: @escaping Factory)
    /// Returns a fresh module instance, or nil if the game is not registered or hidden.
    public func makeModule(_ id: GameID) -> (any GameModule)?
    /// Registered and not hidden, in GameID.allCases order.
    public var availableGameIDs: [GameID] { get }
    /// Hides games whose content failed validation (Section 8). Called once at bootstrap.
    public func hide(_ ids: Set<GameID>)
    /// Debug check: every GameID.allCases is registered and module.id == key.
    public func verifyCompleteness() -> [GameRegistryIssue]
}

// App/Composition/GameRegistry+All.swift
import GameEntdecken; import GameWieViele; import GameHoerHin; import GameWasFehlt
import GameBlitzblick; import GameMehrOderWeniger; import GameNachspuren; import GameSchuettelbox
import GameFroschsprung; import GameZahlenmonster; import GameMemory; import GamePunktZuPunkt

extension GameRegistry {
    static func allGames() -> GameRegistry {
        let r = GameRegistry()
        r.register(.entdecken)      { EntdeckenGame() }
        r.register(.wieViele)       { WieVieleGame() }
        r.register(.hoerHin)        { HoerHinGame() }
        r.register(.wasFehlt)       { WasFehltGame() }
        r.register(.blitzblick)     { BlitzblickGame() }
        r.register(.mehrWeniger)    { MehrOderWenigerGame() }
        r.register(.nachspuren)     { NachspurenGame() }
        r.register(.schuettelbox)   { SchuettelboxGame() }
        r.register(.froschsprung)   { FroschsprungGame() }
        r.register(.zahlenmonster)  { ZahlenmonsterGame() }
        r.register(.memory)         { MemoryGame() }
        r.register(.punktZuPunkt)   { PunktZuPunktGame() }
        return r
    }
}

Decision: GameID case names are lowerCamelCase with explicit raw values; the raw value is the stable identifier used in content file names, JSON, audio IDs and persistence:

// ZKCore
public enum GameID: String, CaseIterable, Codable, Sendable {
    case entdecken     = "entdecken"
    case wieViele      = "wie_viele"
    case hoerHin       = "hoer_hin"
    case wasFehlt      = "was_fehlt"
    case blitzblick    = "blitzblick"
    case mehrWeniger   = "mehr_weniger"
    case nachspuren    = "nachspuren"
    case schuettelbox  = "schuettelbox"
    case froschsprung  = "froschsprung"
    case zahlenmonster = "zahlenmonster"
    case memory        = "memory"
    case punktZuPunkt  = "punkt_zu_punkt"
}

Tier (free/premium) is not decided by the registry; it comes from content (games/<gameId>.json, Section 8) and is checked against EntitlementService by the child shell (Section 17).

5.4.4 Bootstrap sequence #

Performed by AppEnvironment.live() while S-01 (splash) is visible. Steps run in this order; none may crash.

The time budget for steps 1-10 is part of the cold-launch budget in Section 24.

5.4.5 RoundResultCoordinator (unit of work per task) #

Games never touch persistence, rewards or the engine. They emit events through GameEventSink (declared in ZKGameKit, event payloads specified in Section 10.13). The app's RoundResultCoordinator (App/Composition/RoundResultCoordinator.swift; the only implementation of GameEventSink, no other router type) performs, for each taskCompleted event, exactly this sequence on the main actor:

1. Map the task event to the engine input (EngineBridge, app target) using the current LearnerSnapshot built from repositories.
2. Call engine.apply(...) (pure) to get new mastery values, Leitner state, difficulty-stepping counters, controller and range-state updates.
3. progress.record(TaskResultWrite): inserts the TaskAttempt, upserts MasteryRecords (primary and secondary skill), updates GameNumberStat, GameProgress (including gameStateJSON when the event carries TaskResult.updatedGameState, Section 10.13.2) and LearningState (Section 7).
4. rewards.recordTaskCompleted(profileID:taskAttemptID:): appends the taskSolved ledger entry and updates the cached balance.
5. Compute newly eligible Zahlenfreunde with the engine's eligibility function (Section 9) and pass the numbers to rewards.befriend(profileID:numbers:).
6. persistence.save() once. This single save makes steps 3-5 atomic (the "Task completed" save point, Section 7.12.2).
7. Publish the returned RewardEvents to the child UI (star fly-in, befriending celebration trigger).

On round completion (roundCompleted) the coordinator performs rewards.recordRoundCompleted(profileID:roundID:), rewards.awardPictureSticker(profileID:stickerID:) when the round emitted a pictureCompleted event (Punkt zu Punkt, Section 10.13.1; the payload carries no profile ID, the coordinator adds it), session counters, milestone checks, then one save() (the "Round completed" save point, Section 7.12.2). On any thrown error in a unit of work, including an out-of-space error, the coordinator calls persistence.rollback(), logs the error, and the child flow continues without the reward animation for that task (never a child-visible error; the parent-area notice rules are in Section 7.12.2).

5.5 Supported Devices, Orientations and Windowing #

5.5.1 Devices #

5.5.2 Orientations #

No screen locks orientation. Layout rules per orientation are owned by Section 19; per-screen behavior by Section 18. A rotation during a task keeps the task state (the round model is independent of layout) and re-lays out within one animation; in-flight drags are cancelled and the dragged item returns to its origin without counting as an answer (Section 10).

5.5.3 iPad windowing #

Decision: every layout must work at any window width of 375 pt or more and any window height of 375 pt or more, on both iPhone and iPad. The app does not set UIRequiresFullScreen.

Explanation:

• Recent iPadOS versions let users freely resize app windows, and Apple has deprecated UIRequiresFullScreen; relying on it to force a full-screen layout is not future-proof and would degrade the app on current iPads.
• The iPhone SE portrait width (375 pt) and landscape height (375 pt) are already the design minimums (Section 19), so a resizable iPad window that is at least that large reuses the same compact layouts.
• Decision: as a best-effort hint, at scene connection the app sets windowScene.sizeRestrictions?.minimumSize = CGSize(width: 375, height: 375) on iPad. Verification step: on the current iPadOS, confirm whether the system honors the minimum size. Whether or not it does, the child area must degrade gracefully below 375 pt: the root child container measures its size and, when width or height is below 375 pt, renders the 375 pt compact layout scaled down uniformly (scaleEffect, aspect-fit, centered, cream background filling the rest). Touch targets are then physically smaller than 60 pt; this is accepted only for such undersized windows. The parent area uses standard adaptive SwiftUI layout and scrolls.
• Decision: one window only. UIApplicationSupportsMultipleScenes = false. Two simultaneous windows could run two child sessions at once, which the session and time-limit model (Section 15) does not support.
• Size-class changes (e.g., window resize from regular to compact) are handled exactly like rotation (5.5.2).

5.6 Concurrency Model #

5.6.1 Rules #

5.6.2 Task lifetimes #

• Views start async work with .task { } so SwiftUI cancels it when the view disappears.
• Long-lived tasks exist only in services: the Transaction.updates listener (ZKStore), the audio event stream consumer (App, LifecycleCoordinator), the session activity ticker (App, Section 15; 1 Hz Task.sleep(for:) loop active only in child mode).
• Every Task that outlives a view is stored in a property and cancelled in the owner's teardown path, except the StoreKit listener.

5.7 App Lifecycle #

LifecycleCoordinator (app target, @MainActor) is the single subscriber to lifecycle signals. It fans out to the services listed below. Behavior visible to the child (pause overlay, session end, time-limit screens) is owned by Sections 10 and 15; this section owns the plumbing.

5.7.1 Signals observed #

5.7.2 Scene phase handling #

5.7.3 Day rollover #

Triggered by a significant-time-change notification, by returning to .active on a different local date, or by the 1 Hz session ticker detecting a date change while in child mode. Two dates are distinguished:

• The trusted local date (TrustedDayClock, Section 15.12) alone drives time-limit state: DailyUsage attribution (close the current accumulation and start a new row for the new trusted date, Section 7.5.9) and the lock "until local midnight" (a locked child is unlocked only when the trusted date changes, Section 15.8). Setting the device clock forward therefore does not unlock a locked child.
• The AppClock date (clock.today) drives the daily Abenteuer availability (Section 15.10), the engine's due dates (Section 9) and scheduling of pruning for the new date (Section 7.13).

A running round is not interrupted by a rollover.

5.7.4 Audio interruptions #

AudioService translates AVAudioSession.interruptionNotification and routeChangeNotification into AudioEvents. LifecycleCoordinator reacts:

• interruptionBegan: pause the round exactly as for active -> inactive.
• interruptionEnded: await audio.activate(); if the interruption lasted less than 3 s the round resumes automatically, otherwise it stays in the pause overlay until the child taps continue (Section 10.12.3).
• outputRouteLost (headphones unplugged, Bluetooth disconnected): the current voice line stops and the speaker button pulses once; no pause overlay is shown and the round continues (Section 20.12).

Section 20 owns the audio session category and all audio details.

5.7.5 Memory warnings #

On a memory warning, in this order: audio.purgeCaches(keeping:) with the current round's audio IDs; which buffers are dropped and which resident tier is kept is owned by Section 20.10.1; SpriteKit texture atlases of scenes not on screen are released; SwiftUI image caches are not managed manually. The content catalog (under 1 MB decoded) is kept. SwiftData's context is not reset. The event is logged at notice level with the current screen ID. No user-visible effect.

5.8 Build Configurations and Settings Files #

5.8.1 Configurations #

Decision: exactly these three configurations. There is no "Staging" and no "Internal" configuration. Profile exists only so that performance tests can seed data with the test hooks while measuring optimized code; it is never archived for distribution (the release workflow archives Release only, Section 25.20). All TestFlight builds are Release builds without the developer menu; anything that must be testable in TestFlight must be testable in Release (e.g., StoreKit sandbox purchases, Section 17).

Decision: UITEST_HOOKS is set only on the app target (Config/Profile.xcconfig). Local package targets built by Xcode do not receive the app target's SWIFT_ACTIVE_COMPILATION_CONDITIONS, and in the Profile configuration they are built without DEBUG. Therefore package code never branches on UITEST_HOOKS or on test hooks at all: every test hook (launch-argument parsing, DebugSeeder, fake service selection) lives in the app target under #if DEBUG || UITEST_HOOKS, and packages expose only ordinary injectable types (for example AdjustableClock, FakeEntitlementService).

Decision: Debug and Release use the same bundle identifier (default de.zahlenkette.app, Section 1), so StoreKit product IDs (<bundleID>.premium.monthly, <bundleID>.premium.yearly) are identical in both.

5.8.2 xcconfig files #

Warnings-as-errors rule (used by every CI workflow, Section 25.20, and by scripts/ci-local.sh): CI builds pass SWIFT_TREAT_WARNINGS_AS_ERRORS=YES on the xcodebuild command line; the xcconfig files do not set it, so local Debug builds show warnings without failing. Verification step: introduce a deliberate warning in one package target once and confirm the CI build fails; if command-line settings do not reach package targets, add a scripts/check-warnings.sh step that fails when xcodebuild output contains warning: lines from project sources.

5.8.3 StoreKit configuration file #

App/StoreKit/Products.storekit is a locally authored StoreKit configuration file (not synced from App Store Connect) containing the subscription group "Zahlenkette Premium" with the two auto-renewable products de.zahlenkette.app.premium.monthly (1 month) and de.zahlenkette.app.premium.yearly (1 year), their German display names, prices (3,99 EUR and 29,99 EUR), the 7-day free-trial introductory offer on both, and Family Sharing enabled on both (all values owned by Section 17). It is selected in the shared scheme Zahlenkette under Run > Options > StoreKit Configuration for Debug runs, and used by SKTestSession in tests (Section 25). It is not part of the Release build. If the bundle ID changes (Section 1), the product IDs in this file must be updated in the same commit.

5.9 Launch Arguments (Debug and Profile only) #

This table is the single registry of launch arguments; Sections 10, 24, 25 and 29 refer to it and define no arguments of their own. App/Composition/LaunchArguments.swift parses them under #if DEBUG || UITEST_HOOKS (Debug and Profile, 5.8.1); in Release the parser is compiled out and every argument is ignored. All arguments share the -uiTest prefix.

There is no argument that bypasses or auto-solves the parental gate. UI tests solve the gate like a parent (Section 25.10.4).

5.10 Developer Menu (Debug only) #

5.10.1 Access #

The developer menu exists only in the Debug configuration (#if DEBUG around every file in App/Debug/); it is compiled out of Profile and Release, so no TestFlight or App Store build contains it. It is reachable only from inside the parent area, which itself requires the parental gate (Section 16): a single row "Entwicklermenü" at the bottom of the parent dashboard (S-18). There is no other entry point (no long press on a version label, no shake gesture, no hidden taps in child mode, no launch argument). A Release build contains neither the row nor the code; scripts/check-imports.sh also fails if any file outside #if DEBUG references DeveloperMenu.

5.10.2 Contents #

This is the single list of developer-menu panels; Section 29 refers to it.

Developer-menu strings are German like the rest of the parent area but are not part of the translation workload (they live in Localizable.xcstrings marked "Do not translate").

5.11 Capabilities and Entitlements #

App/Zahlenkette.entitlements exists (Xcode creates it with the In-App Purchase capability) and contains no iCloud keys in V1.

5.12 Info.plist #

App/Info.plist is a checked-in file (GENERATE_INFOPLIST_FILE = NO) so every key is reviewable.

Decision: reading raw accelerometer data through CMMotionManager (startAccelerometerUpdates / startDeviceMotionUpdates) does not require a usage-description string and does not show a permission prompt; NSMotionUsageDescription is required for motion-activity and pedometer data (CMMotionActivityManager, CMPedometer), which the app does not use. Verification step (milestone that ships Schüttelbox): run Schüttelbox on a physical iPhone and iPad and confirm no permission prompt appears and no console error mentions a missing purpose string; upload a TestFlight build and confirm App Store Connect reports no missing purpose-string issue. If either check fails, add NSMotionUsageDescription with the value "Die Bewegungssensoren werden nur für das Spiel „Schüttelbox“ genutzt. Es werden keine Bewegungsdaten gespeichert." (no app name, so a rename needs no change) and record it in DECISIONS.md.

The privacy manifest App/PrivacyInfo.xcprivacy is specified in Section 23.

5.13 Repository Layout #

<repository root>/
├── Zahlenkette.xcodeproj                 # app project: targets Zahlenkette, ZahlenketteTests, ZahlenketteUITests
│   └── xcshareddata/xcschemes/Zahlenkette.xcscheme   # shared scheme (StoreKit config; test plans of Section 25.2.2, default Fast)
├── App/                                  # app target sources (composition root)
│   ├── ZahlenketteApp.swift              # @main, creates AppEnvironment, root view, scenePhase hook
│   ├── Composition/
│   │   ├── AppEnvironment.swift
│   │   ├── AppEnvironment+Live.swift
│   │   ├── AppEnvironment+Preview.swift
│   │   ├── LaunchArguments.swift
│   │   ├── GameRegistry+All.swift
│   │   ├── EngineBridge.swift            # SwiftData records <-> engine snapshots
│   │   ├── RoundResultCoordinator.swift  # GameEventSink implementation
│   │   └── LifecycleCoordinator.swift
│   ├── Routing/
│   │   └── AppRouter.swift               # child-mode router (Section 18)
│   ├── Session/                          # session manager, activity ticker, time limit (Section 15.14)
│   ├── ChildMode/                        # S-01..S-16, S-26, S-27 (one folder per screen)
│   │   ├── Splash/  ProfilePicker/  Home/  GamePicker/  GameHost/  RoundEnd/
│   │   ├── Abenteuer/  Garden/  DecorationShop/  Friends/  StickerAlbum/
│   │   ├── AskParent/  TimesUp/  BreakNudge/  Befriended/
│   │   └── Onboarding/                   # S-02, S-03
│   ├── Debug/                            # developer menu, all files wrapped in #if DEBUG
│   ├── TestHooks/                        # DebugSeeder and fake-service selection, wrapped in #if DEBUG || UITEST_HOOKS (5.9)
│   ├── Localization/
│   │   ├── Localizable.xcstrings         # app and parent UI strings (Section 20)
│   │   └── Content.xcstrings             # content lines referenced by JSON (Section 20)
│   ├── Assets.xcassets                   # AppIcon, LaunchBackground color
│   ├── StoreKit/
│   │   └── Products.storekit             # local StoreKit testing (5.8.3)
│   ├── Info.plist
│   ├── PrivacyInfo.xcprivacy             # the privacy manifest (Section 23.6); this is its only location
│   └── Zahlenkette.entitlements
├── Resources/                            # bundled into the app as folder references (paths preserved)
│   ├── Content/                          # Section 8
│   │   ├── manifest.json
│   │   ├── numbers.json
│   │   ├── prompts.json
│   │   ├── decorations.json
│   │   ├── stickers.json
│   │   ├── friends.json
│   │   ├── avatars.json
│   │   ├── games/                        # entdecken.json ... punkt_zu_punkt.json (12 files)
│   │   └── dotpictures/                  # <pictureId>.json (24 files in V1)
│   ├── Audio/
│   │   ├── de/                           # voice lines, <audioId>.m4a (e.g. num.7.m4a)
│   │   └── common/                       # sfx.<key>.m4a, music.<key>.m4a (locale-independent)
│   └── Illustrations.xcassets            # game art, friends, avatars, decorations, dot-picture reveals
├── Packages/
│   └── ZahlenketteKit/
│       ├── Package.swift                 # 5.3.4
│       ├── Sources/
│       │   ├── ZKCore/  ZKLearningEngine/  ZKContent/  ZKPersistence/  ZKAudio/
│       │   ├── ZKDesignSystem/           # contains Resources/Media.xcassets (color tokens, glyphs)
│       │   ├── ZKGameKit/  ZKRewards/  ZKStore/  ZKParentArea/
│       │   └── GameEntdecken/ GameWieViele/ GameHoerHin/ GameWasFehlt/ GameBlitzblick/
│       │       GameMehrOderWeniger/ GameNachspuren/ GameSchuettelbox/ GameFroschsprung/
│       │       GameZahlenmonster/ GameMemory/ GamePunktZuPunkt/
│       └── Tests/
│           ├── TestSupport/              # fakes and fixtures shared by all tests
│           └── <Target>Tests/            # one per library target, e.g. ZKLearningEngineTests/
├── Tests/
│   ├── ZahlenketteTests/                 # app-level integration tests (Swift Testing), incl. content validation of Resources/
│   ├── ZahlenketteUITests/               # XCUITest journeys (Section 25)
│   ├── ZahlenkettePerfTests/             # XCTest performance tests (Section 25.11), run in Profile
│   └── TestPlans/                        # Fast, UISmoke, Full, Performance .xctestplan (Section 25.2.2)
├── Config/
│   ├── Base.xcconfig
│   ├── Brand.xcconfig                    # APP_DISPLAY_NAME + the four URL/e-mail keys (5.8.2)
│   ├── Debug.xcconfig
│   ├── Release.xcconfig
│   └── Profile.xcconfig                  # Release + UITEST_HOOKS (5.8.1)
├── Marketing/
│   ├── de/                               # App Store texts with {{APP_NAME}} token (Section 22)
│   └── rendered/                         # output of render-marketing.sh, git-ignored (Section 6.11.3)
├── scripts/                              # the complete list of repository scripts
│   ├── format.sh                         # swift-format format in place (Section 6.13)
│   ├── lint.sh                           # swift-format lint --strict + check-imports.sh + policy-check.swift + greps (6.13)
│   ├── install-hooks.sh                  # git config core.hooksPath scripts/git-hooks (Section 6.11.3)
│   ├── git-hooks/pre-commit              # runs lint.sh
│   ├── check-imports.sh                  # module graph: Package.swift dependencies and import lines (5.3.3)
│   ├── policy-check.swift                # forbidden symbols and allowlists (Section 23.10)
│   ├── binary-check.sh                   # archived-binary checks (Section 23.10)
│   ├── validate-audio.sh                 # audio file completeness, Release build phase (Section 20.14)
│   ├── check-brand.sh                    # app name appears only via Brand (Section 20.19)
│   ├── check-assets.sh                   # launch asset completeness (Section 29.6.4)
│   ├── render-marketing.sh               # replaces {{APP_NAME}} from Brand.xcconfig into Marketing/rendered/
│   ├── coverage-check.swift              # coverage gate, with coverage-thresholds.json (Section 25.3)
│   ├── coverage-thresholds.json
│   └── ci-local.sh                       # runs the CI workflow steps locally (Section 25.20)
├── ci_scripts/                           # Xcode Cloud hooks: ci_post_clone.sh, ci_pre_xcodebuild.sh, ci_post_xcodebuild.sh (Section 25.20)
├── .swift-format                         # Section 6.13
├── .gitignore                            # Section 6.11
├── .xcode-version                        # exact Xcode version used (5.1.1)
├── DECISIONS.md                          # decision log (Section 6.12)
└── README.md                             # build, test, run instructions; links sections of this spec by number

Rules:

• Resources/Content and Resources/Audio are added to the app target as folder references so their paths are preserved in the bundle (Bundle.main.url(forResource: "Content", withExtension: nil)). The composition root passes that URL to ContentLoader and the Audio URL to AudioService; packages never read Bundle.main paths themselves except Brand (Info.plist) and image lookup by name.
• String Catalogs live in the app target. Package code looks strings up in Bundle.main (the default for String(localized:) and Text), so every key used in a package must exist in the app's catalog; the content-and-strings validation test (Section 8) enforces this.
• Illustrations referenced by content are in Resources/Illustrations.xcassets (app bundle); design-system tokens and glyphs are in the ZKDesignSystem package resource catalog (Bundle.module).
• No file of the repository contains credentials. There are none to store: StoreKit needs no keys in the app.
• A new script is added to the scripts/ list above in the same commit; there are no other dependency or policy scripts (5.3.3). The optional scripts/check-warnings.sh of 5.8.2 is added only if that verification step requires it.

6. Conventions and Coding Standards #

These rules apply to every file in the repository. They exist so that code written in different sessions, by the founder or by AI coding agents, reads as if one person wrote it. Where a rule is checked automatically, the check is named. Tool versions are those in Section 5.

6.1 General Principles #

1. The spec is the source of truth. Code follows the owning section of each concern (section table at the start of the document). When code must deviate or decide something the spec leaves open, the decision is recorded in DECISIONS.md (6.12) in the same commit.
2. English for all code, identifiers, comments, commit messages, DECISIONS.md and logs. German only inside String Catalogs, content JSON string values that are IDs of German things (e.g. the avatar ID avatar.fuchs, content ID formats in Section 8.3), and test fixtures that assert German output.
3. Identifiers are ASCII only. German words in identifiers are transliterated: ä -> ae, ö -> oe, ü -> ue, ß -> ss (HoerHinGame, SchuettelboxScene, groesse). Checked by the swift-format rule IdentifiersMustBeASCII.
4. Source files are UTF-8, LF line endings, one trailing newline.
5. No dead code, no commented-out code, and no unfinished-work marker comments (the conventional uppercase to-do and fix-me tags) in main. An unfinished item is either done or recorded as a DECISIONS.md entry or a task in the milestone plan (Section 27). scripts/lint.sh fails on those marker tags in App/, Packages/ and Tests/.

6.2 Naming #

6.2.1 Types and members #

Game names in identifiers use the transliterated German game name without spaces: Entdecken, WieViele, HoerHin, WasFehlt, Blitzblick, MehrOderWeniger, Nachspuren, Schuettelbox, Froschsprung, Zahlenmonster, Memory, PunktZuPunkt. These match the target names in Section 5.3.2.

6.2.2 Files #

• One primary type per file; the file is named after it (MasteryRecord.swift). Small private helper types used only by that type may live in the same file.
• Extensions adding a conformance or a concern live in <Type>+<Concern>.swift (ChildProfile+Export.swift, GameRegistry+All.swift).
• SwiftData models are nested in the versioned schema enum and live in SchemaV1+<Model>.swift (Section 7.14).
• Protocol and its live implementation live in separate files (AudioService.swift, LiveAudioService.swift).
• Folder names are UpperCamelCase (Repositories/, Views/); resource folders are lowercase where they mirror bundle paths (Resources/Content/games/).

6.2.3 Tests #

Test rules: no sleep/Task.sleep to wait for results (use injected clocks, confirmation, or XCUITest waitForExistence(timeout:) with a maximum of 5 s); no dependence on the real date, time zone, locale or random seed (use FixedClock, a fixed TimeZone(identifier: "Europe/Berlin"), and SplitMix64 with a literal seed); #require instead of force unwraps; each test is independent and uses its own in-memory store.

6.3 Folder Layout per Target #

Every target under Packages/ZahlenketteKit/Sources/ follows the layout below. A folder is created only when it has files.

Game target template (example Hör hin):

Sources/GameHoerHin/
├── HoerHinGame.swift              # GameModule conformance: id, supported skills, makeRound
├── HoerHinParameters.swift        # Decodable parameters of games/hoer_hin.json + validate()
├── HoerHinTask.swift              # the concrete task value type (Sendable, Equatable)
├── HoerHinTaskGenerator.swift     # pure: (PlannedTask, step parameters, level, inout RNG) -> HoerHinTask
├── HoerHinRoundModel.swift        # @MainActor @Observable, drives ZKGameKit's round lifecycle
└── Views/
    ├── HoerHinRoundView.swift
    └── HoerHinAnswerGrid.swift
Tests/GameHoerHinTests/
├── HoerHinParametersTests.swift
├── HoerHinTaskGeneratorTests.swift   # every step x level x range, many seeds
└── HoerHinRoundModelTests.swift

SpriteKit scenes (Wie viele?, Schüttelbox) live in Scene/ inside the game target; PencilKit bridging (Nachspuren) lives in Canvas/; Core Motion shake detection (Schüttelbox, using the injected app-wide CMMotionManager, Section 5.6.1) lives in Motion/.

App target layout is given in Section 5.13: one folder per child-mode screen under App/ChildMode/, each containing <Name>Screen.swift and <Name>Model.swift.

6.4 Data Identifiers, JSON Style and Asset Naming #

6.4.1 JSON #

6.4.2 Other identifier namespaces #

6.4.3 Asset naming #

This subsection is the single asset-naming scheme. Sections 8 (asset-name fields and validation), 19.8 and 21.13 use it unchanged.

Categories are fixed: avatar, theme, friend, deco, dotpic, sticker, obj (counting objects and foods), game, garden, bg, ui, glyph (design-system glyphs). Every asset name matches ^[a-z][a-z0-9_]*$ (the pattern Section 8 validates). Avatars and all other named things use their slug, never an ordinal (avatar_fuchs, not avatar_01). Number-bearing names are zero-padded to two digits where they sort in lists (friend_07, friend_17). Content JSON (assetName, revealAssetName, iconAssetName and similar fields, Section 8) stores the full flat asset name, and content validation checks that each asset exists.

6.5 Localization Key Naming #

Keys follow a dot-separated grammar. Each segment is lowercase snake_case ASCII.

<area>.<context>.<element>[.<qualifier>...]

Rules:

1. Localizable.xcstrings holds app and parent UI keys. Content.xcstrings holds every key referenced by content JSON, including the game.* keys used by content (game titles game.<gameId>.title, step labels game.step.leicht, game.step.mittel, game.step.schwer), number words (number.<n>.word) and picture and sticker names. The content key patterns are owned by Section 8.3 and follow the same segment grammar; Sections 20.17 and 21 use them unchanged.
2. Game display-name keys use the GameID raw value as context: game.<gameId>.title (in Content.xcstrings, rule 1).
3. Keys describe meaning and location, never the German wording. A key is never reused for a different meaning; if the meaning changes, create a new key and delete the old one.
4. Every key has a translator comment in the catalog describing where it appears and any placeholder meaning.
5. Placeholders use positional format specifiers (%1$@, %2$lld). Counts use String Catalog plural variations, never manual if count == 1.
6. The app name is never written into a string value; strings that mention it take a placeholder filled with Brand.appName (Section 20).
7. Code never contains user-facing string literals. It uses String(localized: "parent.dashboard.title"), Text("parent.dashboard.title") (a LocalizedStringKey), or LocalizedStringResource. Keys used from package code must exist in the app's catalogs (Localizable.xcstrings, or Content.xcstrings for content keys) because package lookups resolve against Bundle.main (Section 5.13).
8. Accessibility labels in the parent area are localized strings under the same area with an a11y segment (parent.progress.a11y.cell_format).

6.6 State Management and Dependency Access #

6.7 SwiftUI Composition Rules #

1. Screen = <Name>Screen view + <Name>Model. Screens map 1:1 to screen IDs S-01 to S-27 (Section 18).
2. A view's body stays under about 60 lines. Extract subviews as small structs (preferred, cheaper diffing) rather than long @ViewBuilder computed properties.
3. No business logic in views: no repository or engine calls, no mastery math, no string assembly beyond choosing a key. Views call model intents (model.didTapTile(n)).
4. Child-mode controls come only from ZKDesignSystem (BigButton, NumeralTile, speaker and home buttons, etc.). A raw Button with a text label is forbidden in child mode. Every child tappable applies .childTapTarget(), which enforces the 60 x 60 pt minimum (Section 19) and adds the accessibility identifier.
5. Spacing, sizes, colors, fonts and animation durations come from design tokens (Section 19). Numeric literals for layout are allowed only inside ZKDesignSystem.
6. Layout: prefer stacks, Grid, ViewThatFits, custom Layout types and containerRelativeFrame. GeometryReader is allowed only at a screen root to compute layout metrics once. No fixed-frame screens: every screen must work from 375 x 375 pt upwards (Section 5.5.3).
7. AnyView is forbidden except at the game-host boundary where a GameModule returns its round view (Section 10). Use generics and @ViewBuilder elsewhere.
8. Async work starts in .task, not in onAppear. Work that must survive a view is owned by a model or service.
9. Animations use the Motion tokens, which honor Reduce Motion (Section 19). No withAnimation with literal durations outside ZKDesignSystem.
10. Every screen and component has #Previews for iPhone SE portrait, iPhone SE landscape and an iPad size, using preview fixtures (AppEnvironment.preview(...) in the app target, PreviewFixtures in packages). Previews never touch the on-disk store or play real audio.
11. Navigation follows Section 18 (child router, NavigationStack in the parent area). Views never present parent screens directly from child mode; they call the router, which inserts the parental gate.
12. .sensoryFeedback is attached only through design-system modifiers that check the \.hapticsEnabled environment value (set by the app from the haptics device setting, Section 5.4.1); the haptics map is Section 19.10.

6.8 Error Handling #

6.8.1 Error types #

Each module that can fail defines one error enum. Public APIs use typed throws (throws(PersistenceError)); internal helpers may use untyped throws and map at the boundary.

Every error enum conforms to Error, Sendable, Equatable, CustomStringConvertible. description is for logs and must not contain personal data (no nicknames).

6.8.2 Forbidden constructs in non-test code #

fatalError, precondition, preconditionFailure, try!, as!, force unwrap !, implicitly unwrapped optionals, and unowned. Allowed instead: guard/if let, assert/assertionFailure (Debug-only trap), typed errors, and fallbacks. The single exception is @available(*, unavailable) required init?(coder:) in a UIView subclass, which may call fatalError because it is unreachable. Checked by swift-format rules NeverForceUnwrap, NeverUseForceTry, NeverUseImplicitlyUnwrappedOptionals and by scripts/lint.sh greps for the rest.

6.8.3 Fallback behavior (never crash on content or data problems in Release) #

6.8.4 Presenting errors #

• The child never sees error text, codes or system alerts caused by the app.
• Parent-facing messages are short German sentences from Localizable.xcstrings under the error area, stating what happened and what the parent can do. Raw error descriptions are never shown.
• StoreKit's own system sheets (purchase confirmation, sign-in) are the only system UI that can appear, and only in the parent area.

6.9 Logging #

6.10 Accessibility Identifier Convention #

All interactive and test-relevant elements carry an accessibility identifier so XCUITest (Section 25) can find them without relying on German labels. This is the only identifier scheme in the project; Sections 10, 19, 23, 24 and 25 use it and define no other prefix (no child., game., gate., settings. or childHome. prefixes).

Format:

<screen>.<element>[.<qualifier>]

• <screen> is the screen ID from Section 18 without the hyphen: S01 ... S27. In the game container S-07, elements owned by the shared framework (Section 10) use S07.<element> in every game; elements that exist only in one game use S07.<gameId>.<element>.
• Every screen's root view carries <screen>.root (e.g. S05.root), used by UI tests to wait for a screen.
• <element> is lowerCamelCase and names the role, not the look: speaker, home, answer, gameTile, avatarTile, keypadKey, confirm, lockBadge, progressDot, decorationSlot.
• <qualifier> distinguishes repeated elements by stable data, never by screen position: a number (S07.answer.7), a game ID (S06.gameTile.hoer_hin), a profile index in creation order (S04.avatarTile.0), a grid slot (S11.decorationSlot.3_1), a digit (S17.keypadKey.8).

Examples:

All identifiers are defined as static string constants or builder functions in ZKCore/Accessibility/A11yID.swift (pure strings, no UI import) so that app, packages and the UI-test target use the same values. Identifiers are never localized and never shown. Accessibility labels (what VoiceOver reads) are separate and localized (6.5, Section 19).

6.11 Git Workflow #

The founder works alone with AI coding agents. The workflow keeps main always releasable and every change traceable to the spec.

6.11.1 Branches #

One branch covers one task from the milestone plan. An AI agent session starts from an up-to-date main, works on its branch, runs scripts/lint.sh and the full test plan, and merges with a squash merge (via a pull request on the hosting service if one is used, otherwise git merge --squash locally). Branches are deleted after merge.

6.11.2 Commit messages #

Conventional Commits:

<type>(<scope>): <imperative summary, max 72 chars>

<body: what changed and why, wrapped at 72 chars>

Spec: <section numbers implemented or affected, e.g. 9.4, 9.6>
Decision: <DECISIONS.md IDs added or used, e.g. D-0012> (omit if none)
<attribution trailers required by the agent tooling, if any>

• type: as for branches, plus perf and build.
• scope: module short name (core, engine, content, persistence, audio, design, gamekit, rewards, store, parent, app), a game (game-hoer-hin), or repo, ci, assets, marketing.
• The squash-merge commit on main uses the same format; its summary describes the whole branch.
• Tags: v<MARKETING_VERSION> (e.g. v1.0.0) on the exact commit that produced an App Store build; TestFlight-only builds are not tagged. CURRENT_PROJECT_VERSION increases monotonically with every uploaded build.

6.11.3 Repository hygiene #

.gitignore contains at least:

.DS_Store
xcuserdata/
*.xcuserstate
DerivedData/
build/
.build/
.swiftpm/
*.ipa
*.dSYM.zip
*.xcresult
*.p8
*.p12
*.mobileprovision
/Marketing/rendered/

• Final audio (.m4a) and illustrations are committed. Recording masters (WAV sessions) and illustration source files are stored outside the repository by the founder. Decision: no Git LFS in V1; the committed binary assets (audio and illustrations within the download-size budget of Section 24) are manageable, and avoiding LFS keeps Xcode Cloud setup simple.
• A pre-commit hook scripts/git-hooks/pre-commit runs scripts/lint.sh. Enable it once per clone with scripts/install-hooks.sh, which runs git config core.hooksPath scripts/git-hooks.
• scripts/render-marketing.sh writes rendered marketing texts to Marketing/rendered/, which is ignored.

6.12 Decision Log and Code Review #

6.12.1 DECISIONS.md #

A single Markdown file at the repository root. This subsection defines its only entry format; Sections 1.4 and 29.5 refer to it. Each entry starts with a bold title line **D-NNNN: <title>** (log ID: D- plus a four-digit running number, never reused) followed by the fields below. Append-only: new entries are added at the end; entries are never edited in substance; a changed decision gets a new entry that supersedes the old one.

Entry format:

**D-0007: Warnings-as-errors reaches package targets via xcodebuild setting**

- Date: 2026-10-14
- Status: accepted
- Spec: 5.8.2
- References: none
- Context: The spec asks to verify whether SWIFT_TREAT_WARNINGS_AS_ERRORS on the
  command line applies to local package targets.
- Decision: Verified with a deliberate warning in ZKCore; the CI build failed as intended.
  No extra script needed.
- Consequences: None.

Allowed values of Status (complete list):

References lists related items: earlier entries (D-0003), Section 1.2 question IDs written with their section number (1.2 D-15) so they are never confused with log IDs, and Section 28.2 revisit items by their IDs (RV-NN, e.g. RV-07).

Record an entry when:

1. The spec says "record in DECISIONS.md" (for example the verification steps in Sections 5.1.1, 5.4.1, 5.5.3, 5.8.2, 5.12 and 7.15).
2. Code deviates from the spec, for any reason.
3. The spec is silent and a non-trivial choice was made (anything another agent could plausibly have done differently).
4. A new Apple framework, a new @unchecked Sendable confinement wrapper, a raised tools version, or a toolchain change (.xcode-version) is introduced.

The first entries created in milestone M0 are: D-0001 exact Xcode version, D-0002 Swift Testing on the minimum-OS simulator runtime (outcome, Section 5.1.1), D-0003 environment default variant (5.4.1), D-0004 warnings-as-errors verification (5.8.2). Later milestones add the motion usage-string verification (5.12), the iPad minimum window size verification (5.5.3) and the CloudKit dry run (7.15.1).

6.12.2 Code review checklist #

Every branch is reviewed against this list before merging (by the founder, or by a second AI agent session acting as reviewer). Items marked (auto) are checked by scripts or the build.

Architecture and scope

• Change implements only the task of this branch; spec sections cited in the commit.
• (auto) No new dependency in Package.swift other than local targets; no package reference in the Xcode project.
• (auto) Module graph respected (scripts/check-imports.sh); games import nothing forbidden.
• No network API use (URLSession, Network), no analytics, no notifications, no tracking (Section 23 check).
• No prices, purchase UI or external links reachable in child mode without the parental gate.
• Deviations or new choices recorded in DECISIONS.md.

Correctness

• Engine code is pure: no clock, RNG, persistence or UI access except injected parameters.
• Canonical numbers (mastery gains, intervals, prices, limits) are named constants referencing their owning section; no duplicated literals.
• All persistence writes go through repositories inside a unit of work ending in one save() (Section 7.12.2).
• New or changed SwiftData properties follow the CloudKit rules (Section 7.2) and the migration rules (Section 7.14).
• Every new content reference (audio ID, string key, asset name) exists and passes content validation.
• Edge cases from the owning section have tests.

Concurrency and safety

• (auto) Zero warnings in the Swift language mode of Section 5.
• Main-actor isolation explicit on UI types; no @unchecked Sendable without a DECISIONS.md entry.
• (auto) No forbidden constructs (6.8.2), no print, no Date() / Calendar.current outside allowed places, no unfinished-work marker comments.

UI and accessibility

• Checked on iPhone SE portrait and landscape and one iPad size (previews or simulator screenshots attached to the PR/merge notes).
• Child tappables at least 60 x 60 pt; child controls are pictures or numerals only.
• Accessibility identifiers per 6.10; parent-area VoiceOver labels localized.
• Reduce Motion variant present for new animations; no flashing above 3 Hz; celebrations at most 2.5 s.
• Sound-off path works (voice, music and SFX all off).
• No hardcoded user-facing strings; new keys have translator comments.

Tests and quality

• (auto) All tests in Zahlenkette.xctestplan pass; content validation passes.
• New logic has unit tests with deterministic clock and RNG; test names follow 6.2.3.
• (auto) swift-format lint --strict clean.
• Logs contain no personal data; log levels per 6.9.

6.13 Formatting with swift-format #

Formatting and style linting use only swift-format, which ships with the toolchain of Section 5. No third-party linters or formatters (no SwiftLint, no SwiftFormat by Nick Lockwood).

Commands (wrapped by the scripts):

# scripts/format.sh — rewrite files in place
xcrun swift-format format --in-place --recursive --parallel \
  --configuration .swift-format App Packages Tests

# scripts/lint.sh — fail on any violation, then run the repository checks
xcrun swift-format lint --strict --recursive --parallel \
  --configuration .swift-format App Packages Tests
scripts/check-imports.sh
xcrun swift scripts/policy-check.swift

scripts/lint.sh additionally greps App/, Packages/*/Sources/ and Tests/ and fails on: the uppercase to-do and fix-me marker tags, print(, debugPrint(, NSLog(, fatalError( (except the documented init?(coder:) exception), precondition(, try!, as!, ObservableObject, @Published, @StateObject, @ObservedObject, @EnvironmentObject, @Query, UserDefaults outside the allowlist in 6.6, Date() / Date.now / Calendar.current outside ZKCore/Time/ and test targets, URLSession, import Network. The framework and symbol allowlists of Section 23.10 (for example mach_continuous_time only in ZKCore/Time/TrustedDayClock.swift, no import MessageUI anywhere) are enforced by scripts/policy-check.swift.

Committed configuration file .swift-format at the repository root:

{
  "version": 1,
  "lineLength": 120,
  "indentation": { "spaces": 4 },
  "tabWidth": 4,
  "maximumBlankLines": 1,
  "respectsExistingLineBreaks": true,
  "lineBreakBeforeControlFlowKeywords": false,
  "lineBreakBeforeEachArgument": false,
  "lineBreakBeforeEachGenericRequirement": false,
  "prioritizeKeepingFunctionOutputTogether": true,
  "indentConditionalCompilationBlocks": true,
  "indentSwitchCaseLabels": false,
  "lineBreakAroundMultilineExpressionChainComponents": false,
  "spacesAroundRangeFormationOperators": false,
  "multiElementCollectionTrailingCommas": true,
  "fileScopedDeclarationPrivacy": { "accessLevel": "private" },
  "rules": {
    "AllPublicDeclarationsHaveDocumentation": false,
    "AlwaysUseLiteralForEmptyCollectionInit": true,
    "AlwaysUseLowerCamelCase": true,
    "AmbiguousTrailingClosureOverload": true,
    "BeginDocumentationCommentWithOneLineSummary": false,
    "DoNotUseSemicolons": true,
    "DontRepeatTypeInStaticProperties": true,
    "FileScopedDeclarationPrivacy": true,
    "FullyIndirectEnum": true,
    "GroupNumericLiterals": true,
    "IdentifiersMustBeASCII": true,
    "NeverForceUnwrap": true,
    "NeverUseForceTry": true,
    "NeverUseImplicitlyUnwrappedOptionals": true,
    "NoAccessLevelOnExtensionDeclaration": true,
    "NoAssignmentInExpressions": true,
    "NoBlockComments": true,
    "NoCasesWithOnlyFallthrough": true,
    "NoEmptyTrailingClosureParentheses": true,
    "NoLabelsInCasePatterns": true,
    "NoLeadingUnderscores": true,
    "NoParensAroundConditions": true,
    "NoPlaygroundLiterals": true,
    "NoVoidReturnOnFunctionSignature": true,
    "OmitExplicitReturns": false,
    "OneCasePerLine": true,
    "OneVariableDeclarationPerLine": true,
    "OnlyOneTrailingClosureArgument": true,
    "OrderedImports": true,
    "ReplaceForEachWithForLoop": true,
    "ReturnVoidInsteadOfEmptyTuple": true,
    "TypeNamesShouldBeCapitalized": true,
    "UseEarlyExits": false,
    "UseExplicitNilCheckInConditions": true,
    "UseLetInEveryBoundCaseVariable": true,
    "UseShorthandTypeNames": true,
    "UseSingleLinePropertyGetter": true,
    "UseSynthesizedInitializer": true,
    "UseTripleSlashForDocumentationComments": true,
    "UseWhereClausesInForLoops": false,
    "ValidateDocumentationComments": false
  }
}

Notes:

• Verification step (milestone M0): run xcrun swift-format dump-configuration and compare its key and rule names with the file above. If the installed swift-format reports an unknown key or rule, remove or rename it to the toolchain's name and record the change in DECISIONS.md. The intent of each setting stays: 4-space indentation, 120-column lines, no force unwraps or force tries, ASCII identifiers, ordered imports.
• Suppression: // swift-format-ignore: <RuleName> on the line before a declaration is allowed only with a trailing reason comment, and never for NeverForceUnwrap, NeverUseForceTry or IdentifiersMustBeASCII.
• Xcode's editor settings for the project (in the shared project settings) match: 4 spaces, no tabs, page guide at 120, trim trailing whitespace.

6.14 Swift Language Rules #

6.15 Comments and Documentation in the Repository #

• Code comments explain why, not what. A comment that restates the code is removed in review.
• A spec reference in a comment uses the form // Spec 9.4 so it can be grepped.
• README.md contains: prerequisites (Section 5.1), how to open and build, how to run tests, how to run lint and format, how to use the StoreKit configuration, how to reach the developer menu, and the list of scripts. It does not duplicate the spec.

7. Data Model and Persistence #

This section defines every persisted entity, its fields and defaults, the storage stack, repositories, retention, integrity checks, migrations, the V1.1 iCloud sync enablement, the export file format and the reset/delete semantics. The meaning of learning values (how scores change, when a range widens) is owned by Section 9; the meaning of reward values by Section 14; session and time-limit accounting by Section 15. This section owns how and where those values are stored.

7.1 Scope and Principles #

1. All child data lives in one SwiftData store on the device, module ZKPersistence (Section 5.3.2). V1 stores data locally only; nothing is sent anywhere.
2. The schema is CloudKit-compatible from day one (7.2), so that V1.1 iCloud sync (private database, same Apple ID only) is enabled by configuration alone, without a schema migration (7.15).
3. The store holds child data only. Device-level preferences live in UserDefaults (7.9). The subscription entitlement is not stored in SwiftData (7.8; Section 17).
4. Data minimization: no real names, no birthdates, no photos, no audio recordings, no location, no identifiers that leave the device. The optional nickname (0-20 characters) is the only free text.
5. Append-only where history matters (star ledger, awards), aggregate where volume matters (mastery, daily usage), prune raw logs after a fixed period (attempts and sessions after 90 days).
6. Every write goes through a repository into the single main-actor ModelContext and is committed by one explicit save() per unit of work (7.12.2).

7.2 CloudKit-Compatible Modeling Rules #

7.2.1 Rules #

7.2.2 Automated compatibility check #