Define knowledge persistence requirements

AGRARIAN_DEVELOPMENT_ROADMAP.md

@@ -889,7 +889,7 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
 - [x] Add a small MVP question bank for elementary survival knowledge. Added six elementary survival question records to `Docs/KnowledgeAndSkillFoundation.md` for fire clearance, potable water, cold exposure, shelter drainage, bleeding care, and fiber identification, each with answer options, correct answer, and practical feedback.
 - [x] Define when deeper questions should matter: quality improvements, safer work, complex crafting, teaching others, and advanced branches. Added deeper-question timing rules to `Docs/KnowledgeAndSkillFoundation.md`, keeping advanced checks out of the first survival loop while tying them to quality improvements, safer work, complex crafting, teaching others, and advanced branches.
 - [x] Add design notes for avoiding exploit farming and rote memorization. Added exploit and rote-memorization guardrails to `Docs/KnowledgeAndSkillFoundation.md`, covering diminishing returns, meaningful action context, repeated prompt suppression, recovery-only credit, learned-concept separation, and varied wording to reward decisions and practice instead of low-cost repetition.
-- [ ] Add persistence requirements for knowledge, skill experience, learned concepts, failed attempts, and tutorial state.
+- [x] Add persistence requirements for knowledge, skill experience, learned concepts, failed attempts, and tutorial state. Added knowledge persistence requirements to `Docs/KnowledgeAndSkillFoundation.md`, defining saved profile IDs, learned concepts, practical skill experience, mastery tiers, failed-attempt feedback history, tutorial/prompt state, question cooldowns, teaching/observation events, schema versioning, server authority, and reset-farming prevention.
 - [ ] Add multiplayer rules for teaching, observation, shared work, and group skill benefits.
 
 ---

Docs/KnowledgeAndSkillFoundation.md

@@ -536,3 +536,40 @@ Guardrails:
 
 Anti-exploit rule: rewards should come from meaningful decisions, varied
 practice, and good recovery, not from low-cost repetition.
+
+## Knowledge Persistence Requirements
+
+Knowledge and skill state must survive save/load, server restarts, and future
+character handoff systems without resetting learning progress or tutorial
+fatigue.
+
+Persisted state:
+
+- Stable knowledge profile ID linked to the player character or NPC.
+- Learned concepts by stable concept ID.
+- Practical skill experience by taxonomy domain.
+- Mastery/confidence tier per topic, separate from raw experience.
+- Failed attempts that produced useful feedback, including cause category,
+  recovery action, and recent cooldown state.
+- Tutorial and contextual prompt state: seen, dismissed, repeated, snoozed, and
+  next eligible display time.
+- Optional knowledge checks answered, skipped, failed, or recently displayed.
+- Teaching, observation, and shared-work learning events that granted credit.
+- Schema version, migration marker, and source build/version for future cleanup.
+
+Save/load rules:
+
+- The server is authoritative for writes in multiplayer.
+- Client UI may cache prompt visibility, but save data comes from validated
+  server state.
+- Save enough recent action and prompt history to prevent reset-based farming.
+- Keep learned concepts stable across wording changes in the question bank.
+- Preserve failed attempts long enough to support better feedback and avoid
+  repeating the same hint every few seconds.
+- Store tutorial state per character/profile, not globally across all worlds.
+- Never store private credentials, personal account data, or real-world source
+  notes in player save records.
+
+Persistence rule: learning state should make a returning character feel
+continuous while giving designers enough history to tune teaching, feedback, and
+anti-exploit behavior.

Scripts/verify_knowledge_persistence_requirements.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Verify knowledge and skill persistence requirements 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: [
+        "## Knowledge Persistence Requirements",
+        "Stable knowledge profile ID",
+        "Learned concepts by stable concept ID.",
+        "Practical skill experience by taxonomy domain.",
+        "Failed attempts that produced useful feedback",
+        "Tutorial and contextual prompt state",
+        "Optional knowledge checks answered, skipped, failed, or recently displayed.",
+        "Teaching, observation, and shared-work learning events",
+        "Schema version, migration marker",
+        "The server is authoritative for writes in multiplayer.",
+        "Persistence rule:",
+    ],
+    ROADMAP: [
+        "[x] Add persistence requirements for knowledge, skill experience, learned concepts, failed attempts, and tutorial state.",
+    ],
+}
+
+
+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: knowledge persistence requirements are documented.")
+
+
+if __name__ == "__main__":
+    main()