Phase 1 Specification and Invariants

Relevant Source Files

• README.md
• CHANGELOG.md
• planning/palee_cli_spec.md
• planning/PHASE_2_GAPS.md
• planning/invariants.md

This page summarizes the foundational specifications, architectural requirements, and safety invariants established for Phase 1 of the PALEE (Personal Active Learning & Evaluation Engine) CLI. Phase 1 focuses on a deterministic, AI-free core that handles storage, spaced repetition, and dependency management with high reliability.

1. Solution Architecture

PALEE is designed with a strict separation of concerns, ensuring that the engine remains deterministic and reliable even when AI features are added in later phases planning/palee_cli_spec.md#20-22

1.1 Architectural Layers

Layer	Responsibility	Key Files
Storage	Obsidian vault as source of truth, atomic writes, and locking.	src/storage/
Engine Core	Pure library for SM-2, mastery, and dependency graphs.	src/engine/
Tool Interface	Validated mutation contract for state changes.	src/types.ts
CLI Layer	Deterministic commands (e.g., next, plan, review).	src/cli/, bin/palee.ts

Sources: planning/palee_cli_spec.md#23-84

1.2 Data Flow: Command Execution

The following diagram illustrates how a deterministic command (like palee review) flows through the system entities.

CLI to Storage Data Flow

Sources: planning/palee_cli_spec.md#50-83planning/palee_cli_spec.md#139-147planning/invariants.md#5-18

---

2. System Invariants

Invariants are non-negotiable rules that the codebase must satisfy to ensure data integrity and algorithmic correctness.

2.1 Storage Invariants

• Frontmatter Preservation: Updating a PALEE field must preserve the Markdown body byte-for-byte planning/invariants.md#7-8
• Optimistic Concurrency Control (OCC): Any change in file fingerprint during an operation must trigger a conflict (Exit Code 4) and abort the write planning/invariants.md#9-10
• Atomic Writes: Temporary files and renames are used to prevent file truncation during failures planning/invariants.md#14
• Locking: Locks become stale after 60s on Windows and 120s elsewhere; heartbeats occur every 15s planning/invariants.md#11

2.2 SM-2 and Mastery Invariants

• SM-2 Bounds: The ease_factor must never drop below 1.30planning/invariants.md#23
• Interval Logic: A quality < 3 result resets repetition to 0 and interval to 1 planning/invariants.md#25
• Mastery Calculation: topic_mastery is calculated as round((conceptual + practical + debug + (feynman * 2)) / 5, 4)planning/invariants.md#33

Sources: planning/invariants.md#5-39planning/palee_cli_spec.md#149-160

---

3. Command Contracts

Phase 1 implements a set of deterministic commands designed for both human use and machine integration via the --json flag.

Command	Purpose	Output/Contract
adopt	Injects palee_id and schema into a note.	Adds palee_schema: 1planning/palee_cli_spec.md#122-125
next	Suggests the next topic based on due date and dependencies.	Supports --json for automation planning/palee_cli_spec.md
plan	Generates an ordered study session.	Respects depends_on graph planning/palee_cli_spec.md#70
validate	Checks for cycles and missing dependencies.	Reports exact cycle paths planning/invariants.md#37

Topic Identification Logic

The system uses a stable palee_id as the primary identifier. Topic matching implemented in Phase 1 is per-command: review matches an exact ID, a partial ID substring, or a case-insensitive title substring and requires a unique match — multiple candidates error with exit code 2 (src/cli/review.ts); progress matches the same way but takes the first match (src/cli/progress.ts). session start/session end do not match at all: --topic is accepted verbatim (trimmed; (none) means no active topic), with hot memory's active_topic as the fallback when the flag is omitted (resolveSessionTopic in src/cli/session.ts). The full precedence ladder — exact ID, exact title/filename, legacy alias, normalized slug, then token-distance match — is the specified contract planning/invariants.md#42 with the interactive disambiguation contract in planning/palee_cli_spec.md#203, and is tracked as Planned in 08-2

Entity Mapping: Natural Language to Code

Sources: src/types.tssrc/engine/sm2.tssrc/engine/dependency.tssrc/storage/vault-walker.ts

---

4. Phase 1 Completion Status

All Phase 1 gates have been verified as of August 2026.

Resolved Issues & Implemented Features

• JSON Support: Implemented across all reading commands (next, plan, progress, dashboard, validate, session list) planning/palee_cli_spec.md
• Batch Adoption: Fully implemented in palee adopt with --all, --include, --exclude, --tag, and --dry-run src/cli/adopt.ts
• Markdown Roadmap Import: Supports importing from .md files containing YAML frontmatter or YAML code fences src/storage/roadmap-parser.ts
• Difficulty Normalization: A runtime helper now maps numeric (1-5) and string inputs to the Difficulty enum planning/invariants.md
• Empty States: Actionable onboarding guidance replaces empty terminal dumps planning/palee_cli_spec.md

Known Gaps (Phase 2)

• AI Integration: test and tutor commands remain stubs until Phase 2 AI module implementation planning/PHASE_2_GAPS.md#112-128
• Transactional Auto-Fix: validate --fix remains a future enhancement — fixability is modeled in rule metadata (fixable), the engine itself is deferred per ADR-0008

Sources: planning/invariants.mdplanning/PHASE_2_GAPS.md#1-160