Architectural Decision Records (ADRs)

This directory records significant architectural and design decisions for PALEE.

Status vocabulary

Use one of Proposed, Accepted, or Superseded by ADR-nnnn. If a later ADR changes part of a decision without replacing the whole record, add an Amended by ADR-nnnn line and a short note at the affected decision.

## Status

Accepted (YYYY-MM-DD)

Amended by ADR-nnnn: one-line scope of the change.

Page titles and content headings use Title Case. ADR titles follow the same convention; ADR section headings use the standard template headings (Status, Context, Decision, Consequences). Keep one convention within a page rather than mixing them.

Index

• ADR-0001: SuperMemo SM-2 Spaced Repetition Algorithm
• ADR-0002: Atomic File Locking and Optimistic Concurrency Control
• ADR-0003: Non-Destructive Frontmatter Updates via YAML Document API
• ADR-0004: Four-Pillar Pedagogical Assessment Model
• ADR-0005: Concurrency-Hardened Storage and Automated Schema Migration
• ADR-0006: Phase 1 Concurrency Resilience, Storage Layer Isolation & Session Duration Tracking
• ADR-0007: Hot-Memory Read-State Contract
• ADR-0008: Validation Rule Framework — Architecture and Product Decisions
• ADR-0009: The Gating Model — What May Lock a Note
• ADR-0010: Tier-0 Hygiene Classification for Batch Adoption
• ADR-0011: Tiered Auto-Chain — strict | full
• ADR-0012: Declared Prerequisites — Reading a Note's Own Text
• ADR-0013: Per-Edge Blocking Policy and OR-Groups
• ADR-0014: Atomic-Write Durability and Vault Containment
• ADR-0015: Identity Preservation — An Identity on Disk Is Not a Command's to Invent
• ADR-0016: Frontmatter Byte Fidelity and Unicode Fold Discipline
• ADR-0017: Roadmap Import Safety
• ADR-0018: Note Read Path, Caching, and Locking
• ADR-0019: Session-Memory Lifecycle and Staleness Clamps
• ADR-0020: Readiness and Scheduling Contracts
• ADR-0021: The Assessment Surface
• ADR-0022: Adoption — Non-Destructive, Reversible, Honest About Filters
• ADR-0023: migrate --relabel-ties as the Migration Surface
• ADR-0024: Exit Codes and the Machine-Readable Error Contract
• ADR-0025: The Application Layer and the CLI Boundary
• ADR-0026: Test Discipline — Falsifiability Over Ceremony
• ADR-0027: The AI Provider Adapter and Its Network Boundary
• ADR-0028: Phase-2 Design Directions
• ADR-0029: Test-Time CLI Launch Policy
• ADR-0030: Installed-Artifact CI Evidence
• ADR-0031: Documentation Truth - Current-State Docs, Labeled History
• ADR-0032: Direct Spawn Bounding — What ADR-0029 Claimed, and the Check That Pins It
• ADR-0033: The Update Command and Its npm Child Process
• ADR-0034: Reclaiming a Killed Writer's Temporary File
• ADR-0035: --fix Mastery Repair and Partial Pillar Eligibility
• ADR-0036: Bounded Lock Acquisition — A Non-Empty Lockdir Is Not a Retry Signal
• ADR-0037: Manifest Values Reach the Shell as Data, Never as Interpolation