8. Planning and Design Documents

Relevant Source Files

• planning/PHASE_2_GAPS.md
• docs/adr/0008-validation-framework-decisions.md
• planning/ai_module_design.md
• planning/cicd_dependency_management_proposal.md
• planning/example_workflows.md
• planning/invariants.md
• planning/memory_design.md
• planning/palee_cli_spec.md
• planning/roadmap_design.md
• planning/storage_design.md

This section serves as a central index for the planning/ directory, containing the foundational specifications, design proposals, and roadmaps that guide the PALEE codebase. These documents capture the architectural decisions, system invariants, and the multi-phase execution strategy used to build the engine.

8.1 Phase 1 Specification and Invariants

Phase 1 focuses on the deterministic core of PALEE: the storage layer, the SM-2 scheduling engine, and basic CLI management. The design ensures that PALEE can safely operate on an Obsidian vault as a source of truth without corrupting user data.

Core Specifications

• Problem Statement & Architecture: The system follows a three-layer architecture (Storage → Engine Core → CLI) designed to maintain a deterministic learning loop planning/palee_cli_spec.md
• Storage Invariants: The system guarantees that updating a PALEE field preserves the Markdown body byte-for-byte planning/invariants.md#7-8 It uses an atomic write protocol (temp file → fsync → rename) to prevent data loss planning/storage_design.md#39-52
• SM-2 Algorithm: Scheduling follows the SM-2 logic where ease_factor is capped at a minimum of 1.30 planning/invariants.md#23 and intervals progress through a 1, 6, round(prev * EF) sequence planning/invariants.md#26

Implementation Tracking

The implementation was managed through a gate-controlled checklist, ensuring Gate 0 (Setup) through Gate 5 (Packaging) met all acceptance criteria before proceeding CHANGELOG.md The sprint-scoped planning logs that tracked day-to-day execution (trigger tracker, issue log, phase checklist) were removed once Phase 1 completed — the durable records are planning/invariants.md, docs/adr/, and the closed issue/PR history.

For details, see Phase 1 Specification and Invariants

---

8.2 Future: AI Module and Phase 2 Design

Phase 2 introduces the "Personal Active Learning" aspect via Large Language Models (LLMs). This layer provides intelligent tutoring, Feynman-style assessments, and automated roadmap generation.

AI Tutoring & Sessions

• Feynman Testing: The palee test command will use AI to conduct conceptual probes and grade responses across four dimensions: conceptual, practical, debug, and feynman planning/ai_module_design.md#88-102
• Session Continuity: PALEE uses a "Hot Memory" system (hot.md) limited to 250 words to provide the AI with immediate context of the learner's current position without exceeding token limits planning/memory_design.md#41-43
• Tool-Calling Loop: The AI interacts with the engine through a read-only tool interface, ensuring the LLM cannot mutate the vault without explicit learner confirmation planning/ai_module_design.md#64-80

Roadmap Generation

Future iterations will support guided interviews to generate personalized learning paths. This mode will collect learner goals, constraints, and time availability to propose a Topic DAG (Directed Acyclic Graph) planning/roadmap_design.md#15-30

For details, see Future: AI Module and Phase 2 Design

---

System Integration Diagrams

From Requirements to Code Entities

The following diagram maps high-level planning concepts to the specific TypeScript entities and storage files that implement them.

Planning to Entity Mapping

Sources:planning/invariants.mdplanning/storage_design.mdsrc/types.ts

Storage & Memory Lifecycle

This diagram bridges the design intent for session continuity with the actual file-system structure managed by the Storage layer.

Session Lifecycle Mapping

Sources:planning/memory_design.md#91-100planning/ai_module_design.md#7-8src/storage/memory.ts

Planning Resource Matrix

Document	Purpose	Key Symbols / Concepts
invariants.md	Success Criteria	ease_factor >= 1.3, OCC conflict, Heartbeat
storage_design.md	Data Integrity	Atomic Write, Fingerprint, Lock Heartbeat
ai_module_design.md	AI Integration	Tool-Calling Loop, Assessment Proposal
memory_design.md	Continuity	hot.md, DRAFT-S-*, 250-word cap
roadmap_design.md	Curriculum	Topic DAG, R- prefix, Guided Interview
PHASE_1_ISSUES.md (removed)	Bug Tracking	Superseded by the GitHub issue tracker and closed-issue history

Sources:planning/invariants.mdplanning/storage_design.mdplanning/ai_module_design.mdplanning/memory_design.mdplanning/roadmap_design.mdplanning/palee_cli_spec.md