Design optional knowledge checks

AGRARIAN_DEVELOPMENT_ROADMAP.md

@@ -882,7 +882,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
 - [x] Define how knowledge affects survival actions: fewer mistakes, safer attempts, better yields, lower injury risk, and more reliable outcomes. Added the knowledge action-effects model to `Docs/KnowledgeAndSkillFoundation.md`, defining how knowledge changes warnings, failed-action reasons, safety, yield/waste, injury risk, and outcome reliability without silently guaranteeing success or replacing practical experience.
 - [x] Define how practical experience grows through use, repetition, mistakes, and recovery from failure. Added practical experience growth rules to `Docs/KnowledgeAndSkillFoundation.md`, defining gain from meaningful use, diminishing returns for rote repetition, learning from readable mistakes, and extra credit for recovering well from failure.
 - [x] Add first contextual learning prompts for fire safety, potable water, exposure, shelter placement, injury care, and resource identification. Added first contextual prompt specs to `Docs/KnowledgeAndSkillFoundation.md` for fire safety, potable water, exposure, shelter placement, injury care, and resource identification, with trigger examples, prompt intent, sample wording, and the rule that prompts explain immediate risk without pausing the game or forcing a quiz.
-- [ ] Design optional knowledge checks that appear when relevant to the action instead of interrupting basic play.
+- [x] Design optional knowledge checks that appear when relevant to the action instead of interrupting basic play. Added optional knowledge-check rules to `Docs/KnowledgeAndSkillFoundation.md`, defining inline/skippable presentation, action-relevant timing, calm review moments, non-punitive wrong answers, and the rule that checks deepen understanding without gating the first survival loop.
 - [ ] Add player-facing feedback that explains why an action failed or produced poor results.
 - [ ] Define accessibility rules for the learning system: hints, retries, readable wording, no hard lockout from basic survival, and non-punitive practice paths.
 - [ ] Define the first subject content format: topic, concepts, difficulty tier, prerequisite concepts, in-game effect, practice action, and source note.

Docs/KnowledgeAndSkillFoundation.md

@@ -269,3 +269,38 @@ Resource identification:
 
 Prompt rule: contextual prompts should explain the immediate risk or opportunity
 without pausing the game or forcing a quiz.
+
+## Optional Knowledge Checks
+
+Optional knowledge checks should appear when a question naturally belongs to the
+current action. They are not school-test popups and should not interrupt basic
+survival.
+
+Presentation rules:
+
+- Show checks as optional inline choices, short reflection prompts, or camp/journal
+  review cards.
+- Let players continue basic survival without answering.
+- Do not pause combat, weather danger, fire spread, or other time-sensitive
+  events.
+- Avoid repeated prompts after the player has recently answered, skipped, or
+  demonstrated the concept through action.
+
+When checks appear:
+
+- Before a risky improvement path, such as safer fire setup, shelter siting,
+  water treatment, advanced first aid, or higher-quality crafting.
+- After a readable mistake, when the game can ask what likely went wrong.
+- During calm moments near shelter, campfire, rest, journals, mentors, or
+  teaching interactions.
+
+Outcome rules:
+
+- Correct answers can improve confidence, reduce future warnings, unlock clearer
+  explanations, or slightly improve risk/quality modifiers.
+- Wrong answers should explain the correction and may leave the player at normal
+  baseline risk instead of punishing them harshly.
+- Skipping should preserve basic action access.
+
+Knowledge-check rule: checks should deepen understanding and improve outcomes,
+not gate the first survival loop.

Scripts/verify_optional_knowledge_checks.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Verify optional contextual knowledge-check rules are documented."""
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DOC = ROOT / "Docs" / "KnowledgeAndSkillFoundation.md"
+ROADMAP = ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md"
+
+REQUIRED = {
+    DOC: [
+        "## Optional Knowledge Checks",
+        "Presentation rules:",
+        "When checks appear:",
+        "Outcome rules:",
+        "Let players continue basic survival without answering.",
+        "not gate the first survival loop",
+    ],
+    ROADMAP: [
+        "[x] Design optional knowledge checks that appear when relevant to the action instead of interrupting basic play.",
+    ],
+}
+
+
+def main() -> None:
+    missing: list[str] = []
+    for path, snippets in REQUIRED.items():
+        text = path.read_text(encoding="utf-8")
+        for snippet in snippets:
+            if snippet not in text:
+                missing.append(f"{path.relative_to(ROOT)} missing {snippet!r}")
+    if missing:
+        raise SystemExit("FAILED: " + "; ".join(missing))
+    print("OK: optional knowledge-check rules are documented.")
+
+
+if __name__ == "__main__":
+    main()