format: https://specscore.md/feature-specification status: Approved
Feature: Lessons Index
SpecScore.Studio: | Explore | Edit | Ask question | Request change |
Status: Approved Source Ideas: —
Summary
The Lessons Index at spec/lessons/README.md is the concise inventory of process-improvement Lessons. It presents recurrence as derived read-model data, never as a hand-maintained counter.
Problem
Without a canonical index, lessons disappear into retrospectives. A mutable recurrence counter would also race concurrent occurrence writers and create a second, unreliable source of truth.
Behavior
This feature inherits location, section, completeness, and footer rules from Index. It defines only Lesson-specific columns and derived-data behavior.
Index columns
REQ: lesson-index-columns
The ## Lessons table MUST contain, in order: Lesson, Status, Classifications, Occurrences, Last Occurred, and Enforcement. Lesson links to <slug>/README.md; Occurrences and Last Occurred are derived from valid child occurrence JSON (Last Occurred is the maximum occurred_at, with lexical path only as a tie-breaker); Enforcement is the Lesson's declared Control or —. The index MAY be generated or refreshed by tooling, but authors do not edit derived cells to record a new occurrence.
REQ: canonical-only
The index lists every canonical directory-form Lesson exactly once. Legacy single-file Lessons are listed only during the compatibility window and marked Legacy; a retained duplicate is listed with Duplicate Of rather than presented as an independent active rule.
Adherence footer
REQ: adherence-footer
Every lessons index MUST end with an adherence footer per the Adherence Footer feature. The footer URL MUST be https://specscore.md/lessons-index-specification.
Interaction with Other Features
| Feature | Interaction |
|---|---|
| Lesson | Aggregates canonical Lesson metadata and child occurrence-derived values. |
| Index | Inherits shared index structure and completeness rules. |
| Adherence Footer | Supplies the delegated footer mechanism. |
| Document Types Registry | Registers this Index-Kind type at spec/lessons/README.md. |
Acceptance Criteria
AC: index-derives-recurrence
Requirements: lessons-index#req:lesson-index-columns, lessons-index#req:canonical-only
Given two canonical Lessons with occurrence files, when the index is generated or refreshed, then it lists each directory once with the correct derived occurrence count and last-occurrence time. Adding an occurrence changes only child JSON until the generated view is refreshed; it does not make the README a mutable counter.
Open Questions
None at this time.
This document follows the https://specscore.md/feature-specification