diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 4a2eae4..8d6df28 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/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. --- diff --git a/Docs/KnowledgeAndSkillFoundation.md b/Docs/KnowledgeAndSkillFoundation.md index 0527037..9c437a2 100644 --- a/Docs/KnowledgeAndSkillFoundation.md +++ b/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. diff --git a/Scripts/verify_knowledge_persistence_requirements.py b/Scripts/verify_knowledge_persistence_requirements.py new file mode 100644 index 0000000..950c985 --- /dev/null +++ b/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()