@erclx/aitk 0.99.1 → 0.100.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.99.1",
+  "version": "0.100.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-teach/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: claude-teach
+description: Scope boundary for learning a subject across sessions, and the split between the disposable lesson and the durable reference page
+---
+
+# Claude teach requirement
+
+## Gap
+
+Without this skill, a session asked to teach a subject answers in the conversation, so everything it produced dies with the session and the next one starts from nothing. It teaches from recall rather than from a source, so the learner is handed claims nothing was read for and cannot tell which ones. It picks the next topic from the subject's own order rather than from what the learner got wrong, so it teaches past a gap it never measured. It asks nothing about what the learner already knows, so difficulty has no floor and the session lands either below or far above them.
+
+It also produces one output where two are needed. A page written to be worked through once and a page written to be looked up later have different lifetimes and different readers, and merging them yields material that is disposable and gets kept, or durable and carries a quiz nobody can promote. Writing the durable half in a format the authoring gates do not read costs a conversion at the moment it matters most, which is the moment someone tries to promote it.
+
+A session that does record something records the wrong thing. It writes what was taught rather than what the learner retrieved, and a tally of errors carries none of the misconception a later session would work against.
+
+Two failures land specifically on where the folder sits. A workspace resolved against the current directory forks into a copy per linked worktree, so the learning records split and no session sees the whole history. A body naming only the destination path reports success and loses the write, because the file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead.
+
+## Must
+
+- Hold the workspace at the main worktree root, so one learner has one history rather than one per worktree
+- Name the write route for a main-root path from a linked worktree, since a body naming only the destination reports a success that did not happen
+- Settle the learner's starting point by asking, so difficulty sits above a measured floor
+- Research the subject from sources before teaching it, and record what was read and what was found and not opened
+- Place each lesson from the learning records rather than from the subject's order, and open with retrieval on the last wrong answer
+- Split the output by lifetime, sending the worked-through half to lessons and the looked-up half to reference pages in the format the authoring gates read
+- Record the wrong answer itself rather than the count, since that is what the next session places the learner from
+- Report progress against the mission's success lines, so a mission can be called finished
+
+## Must not
+
+- Teach from recall without saying which claims rest on it
+- Write outside the workspace folder, which is what a promotion pass owns rather than this skill
+- Open a second workspace on a subject an existing one already covers
+- Renumber a workspace folder, a lesson, or a learning record, since the number is cited by files already written
+
+## Guards
+
+- No subject named and no existing workspace matching, stop rather than opening a workspace with nothing to learn
+
+## Out of scope
+
+- Promoting a durable page out of the workspace, which is a judgment about public prose and belongs to a separate surface
+- The command surface and the records backup for the folder, which resolve the root in-process and carry the workspace off one disk
+- What a lesson renders as and how a quiz behaves once rendered, which the lesson-craft reference shapes and a rendering layer executes
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so opening a workspace is the learner's call rather than a description match.

package/claude/skills/claude-teach/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: claude-teach
+description: Opens and runs a learning workspace on one subject, holding a mission, resources, numbered lessons, reference pages, a glossary, and learning records that survive across sessions. Use when asked to "teach me X", "open a learning workspace", "I want to learn X", "quiz me on this", "continue the lesson", or "resume my workspace on X". Do NOT use to write project documentation, which belongs to the surface owning that document, and do NOT use to answer one question, which is an ordinary reply.
+disable-model-invocation: true
+argument-hint: <subject to learn, or the topic of the workspace to resume>
+---
+
+# Claude teach
+
+Run a learning workspace on one subject across sessions. The workspace holds what the learner has been through, so a session weeks later resumes from the folder rather than from the conversation.
+
+The shape of the workspace is fixed by `.claude/standards/teach.md`, or `${CLAUDE_SKILL_DIR}/../../standards/teach.md` when the project does not have that file. Read it before writing anything into the folder. The pedagogy sits in `${CLAUDE_SKILL_DIR}/references/pedagogy.md` and the lesson craft in `${CLAUDE_SKILL_DIR}/references/lesson-craft.md`.
+
+## Guards
+
+- If the invocation names no subject and no existing workspace matches, stop: `❌ No subject. Invoke with the subject to learn, or the topic of a workspace to resume.`
+- Never trust recall for what the subject says. Research first, cite what was read, and say what was not.
+- Write nothing outside the workspace folder. A durable page stays in `reference/` until a promotion pass moves it, and this skill runs no promotion.
+- Do not open a second workspace on a subject one already covers. Resume that one.
+
+## Step 0: resolve the workspace root
+
+Workspaces live at the main worktree root, never inside a linked worktree. A copy per worktree forks the learning records, and the learner is one person.
+
+```bash
+git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-
+```
+
+Fall back to the current directory when that reports nothing. Workspaces sit under `<main-root>/.claude/teach/`.
+
+From a linked worktree the file-editing tools refuse every path under that root and offer a worktree copy instead, which is a second file no later session reads. Never take that redirect. Create a file as one plain shell command carrying a heredoc, and change a file that already exists by reading it and writing it back whole through the same route.
+
+## Step 1: open or resume
+
+List the folders under the workspace root. A folder whose topic matches the invocation is a resume, and anything else is a new workspace.
+
+On a resume, read `MISSION.md`, the highest-numbered learning record, and `GLOSSARY.md`. Those three carry where the learner stopped and what they got wrong. Report the mission's success lines with what is already met before teaching anything.
+
+On a new workspace, settle the starting point first, by asking rather than by assuming. Difficulty with no floor under it teaches nobody, and the mission cannot be written without it.
+
+Then take the ordinal from the highest one present, incremented, create the folder as `<nn>-<topic>`, and write all three files the standard requires: `MISSION.md` to the template it carries, `RESOURCES.md` with whatever Step 2 read, and `GLOSSARY.md`, empty of terms until a lesson defines one. A workspace missing any of the three fails its own conformance check the moment anything walks it.
+
+## Step 2: research before teaching
+
+Read the subject from sources rather than from recall. Record every source in `RESOURCES.md` with its link, and list under a leads heading anything found and not opened.
+
+A claim nothing was read for is the failure this step exists against. Where no source is reachable, say so in the lesson and mark what rests on recall.
+
+## Step 3: place the learner
+
+Pick the next lesson from the learning records rather than from the subject's own order. The target is the band immediately past what the learner can already do unaided, which `${CLAUDE_SKILL_DIR}/references/pedagogy.md` states in full.
+
+Open with retrieval on what the last session got wrong, before anything new. A learner who cannot retrieve the previous lesson is not ready for the next one, and moving on anyway buys fluency that decays.
+
+## Step 4: write the lesson and the reference
+
+Two outputs with two lifetimes, and the split decides the format.
+
+- A lesson goes to `lessons/<nnnn>-<slug>.html`, self-contained, carrying its own quiz and the feedback for each answer. It links the shared stylesheet under `assets/` rather than restating styles, and the first lesson in a workspace writes that stylesheet before linking it. A lesson is disposable and is never promoted.
+- A reference page goes to `reference/<slug>.md`, written for a reader with no learner in it. This is the half that survives the workspace, so it is written in markdown to pass the authoring gates a promotion would put it through.
+
+Add every term the lesson defines to `GLOSSARY.md`, in the entry shape the standard fixes.
+
+Follow `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` for what makes a lesson worth returning to. Keep every quiz answer the same length, so formatting leaks no clue about which one is correct.
+
+## Step 5: record what happened
+
+Write `learning-records/<nnnn>-<slug>.md` before the session ends, carrying the lessons covered, what the learner retrieved unaided, what they got wrong with the wrong answer itself, and what to revisit.
+
+Record the wrong answer rather than the count. The next session places the learner from this file, and a tally carries no misconception to work against.
+
+Then restate the mission's success lines with what is now met. A mission whose lines are all met is finished, and saying so is what closes a workspace.
+
+## Output
+
+```plaintext
+✅ <opened|resumed> .claude/teach/<nn>-<topic>/
+Lesson:    .claude/teach/<nn>-<topic>/lessons/<nnnn>-<slug>.html
+Reference: .claude/teach/<nn>-<topic>/reference/<slug>.md
+Record:    .claude/teach/<nn>-<topic>/learning-records/<nnnn>-<slug>.md
+Progress:  <n> of <m> success lines met
+```
+
+Omit the reference line where the lesson produced no durable page. Emit every path from the project root, in the form the project's instruction file sets.

package/claude/skills/claude-teach/references/lesson-craft.md

@@ -0,0 +1,52 @@
+---
+title: Lesson craft reference
+description: Typography, restraint, quiz construction, and what makes a lesson worth returning to
+---
+
+# Lesson craft reference
+
+Judgment rather than shape. The workspace standard fixes where a lesson sits and what it is named, and this file covers what makes one worth opening twice.
+
+## One course, not a pile of pages
+
+A workspace accumulates lessons over weeks. The learner reads them as one body of material, so a lesson that invents its own look reads as someone else's work.
+
+- Write the shared stylesheet into the workspace assets on the first lesson, and link it from every lesson after
+- Promote anything used a second time into that stylesheet. A second use makes it a component of the course.
+- Keep the structural furniture identical across lessons: where the title sits, where the quiz sits, what a correct answer looks like
+- Do not restate styles inside a lesson. A local override is a decision the next lesson has to either copy or contradict.
+
+## Typography
+
+The learner is reading, so the reading surface is the product.
+
+- Set body text at a comfortable reading size with generous line height, and hold the measure to roughly 65 to 75 characters
+- Use one typeface for prose and one for code, and no others
+- Build hierarchy from size and weight rather than from color. Color that carries meaning fails for a reader who cannot see it.
+- Give code blocks room. Cramped code is the part of a lesson a learner skips.
+
+## Restraint
+
+Every element competes with the material for attention.
+
+- Cut any decoration that carries no information
+- Use at most one accent color, reserved for the thing the learner acts on
+- Do not animate anything the learner did not trigger
+- Prefer whitespace over rules and boxes to separate sections
+
+## Quiz construction
+
+The quiz is the retrieval, so a leak in its construction turns it into a reading test.
+
+- Write every option to the same length, in words and in characters. A longer option reads as the considered one.
+- Vary which position holds the correct answer, and never let the order follow the order the material was taught in
+- Make each wrong option a misconception someone actually holds. An obviously wrong option removes itself and shrinks the question.
+- Write feedback for every option, including the correct one, saying why rather than whether
+- Give feedback after the attempt, never alongside the question
+
+## What makes a lesson worth returning to
+
+- The worked example is complete. A learner returning for the example finds the whole thing rather than a fragment they have to reconstruct.
+- The lesson states what it assumes. A returning reader can tell in one line whether they are in the right place.
+- The hard part is named as the hard part. Material that flattens everything to one difficulty gives a returning reader nothing to navigate by.
+- Nothing depends on the session it was written in. A lesson referring to what was discussed is unreadable a week later.

package/claude/skills/claude-teach/references/pedagogy.md

@@ -0,0 +1,67 @@
+---
+title: Pedagogy reference
+description: Fluency against storage strength, retrieval practice, spacing, interleaving, the zone of proximal development, and where difficulty helps
+---
+
+# Pedagogy reference
+
+The rules a lesson is built from. Read this before picking what to teach next, not while writing the markup.
+
+## Fluency is not storage strength
+
+A learner who follows an explanation smoothly has demonstrated that the explanation was clear. That is fluency, and it decays within days. Storage strength is whether the material can be retrieved later without the explanation present, and the two move independently.
+
+The practical consequence is that a lesson cannot report its own success. Only a later retrieval can, which is why the learning record exists and why every session opens by testing the last one rather than by reviewing it.
+
+- Treat a learner's confidence as evidence about the lesson, never about their retention
+- Never advance on the strength of a smooth session. Advance on a retrieval the learner passed unaided.
+
+## Retrieval practice
+
+Pulling an answer out of memory strengthens it far more than reading it again. Recognition is the weak form: a learner who picks the right option from four has done less work than one who produced the answer from nothing.
+
+- Ask before telling. Open with the question, then teach into the gap the attempt exposes.
+- Prefer a question the learner has to produce an answer to over one they select from
+- Let the learner fail an attempt before correcting it. A failed retrieval followed by the answer beats being told first.
+- Do not cue the answer in the question. A question restating the material tests reading rather than memory.
+
+## Spacing
+
+The same total time spread across days beats the same time in one sitting. Forgetting between sessions is the mechanism rather than the cost, because effortful retrieval is what strengthens the trace.
+
+- Revisit a topic after the learner has begun to forget it, not while it is still fresh
+- Widen the gap each time a topic is retrieved correctly, and shorten it after a miss
+- Name what to revisit and roughly when in the learning record, so the next session has a schedule rather than a guess
+
+## Interleaving
+
+Mixing related topics within a session beats finishing one before starting the next. Blocked practice inflates in-session performance and hurts what survives it, because the learner stops having to work out which approach a problem calls for.
+
+- Mix topics inside a session once the learner has a foothold in each
+- Keep problems in a mixed set close enough that telling them apart is the work
+- Do not interleave a topic the learner has never seen. Interleaving discriminates between things already known.
+
+## The zone of proximal development
+
+The productive band is what the learner cannot do alone and can do with support. Below it the session is review, and above it the support carries the whole task and nothing transfers.
+
+- Compute the band from the learning records rather than from the subject's own order
+- Target the first thing the last record shows the learner could not do unaided
+- Withdraw support as the learner succeeds, and restore it on a miss rather than repeating the lesson
+- Where the records show nothing, ask. A guessed starting point misses in both directions.
+
+## Where difficulty helps and where it hurts
+
+Difficulty is not uniformly good. It helps skill acquisition, where the learner is building a procedure they will execute, and it hurts knowledge acquisition, where the learner is taking on facts and structure they do not have yet.
+
+- Introduce new facts and structure in their clearest form, with worked examples and no invented obstacles
+- Add difficulty once the learner is practicing rather than acquiring: withhold the worked step, vary the surface of the problem, delay the feedback
+- Never confuse a hard explanation with a hard problem. A confusing explanation adds load that teaches nothing.
+
+## Sourcing
+
+Parametric recall is confident where it is wrong, and a learner cannot audit it. Every claim in a lesson traces to something read.
+
+- Read the subject from sources before teaching, and record each one with its link
+- Mark any claim resting on recall as resting on recall, in the lesson itself
+- List a source found and not opened as a lead, and never cite it

package/docs/agents/records.md

@@ -7,7 +7,7 @@ description: Validating the session records under .claude/ and the standards cor
 
 ## Validate
 
-`aitk records validate <kind>` reports where a file and the standard governing it disagree. Four kinds are gitignored folders under `.claude/`: `plans`, `groundwork`, `intake`, and `memory`. The fifth is `standards`, the authoring corpus, which is tracked and installed rather than scratch.
+`aitk records validate <kind>` reports where a file and the standard governing it disagree. Five kinds are gitignored folders under `.claude/`: `plans`, `groundwork`, `intake`, `memory`, and `teach`. The sixth is `standards`, the authoring corpus, which is tracked and installed rather than scratch.
 
 ```bash
 aitk records validate plans
@@ -25,17 +25,18 @@ It reads and never writes, and the reason splits by kind. A session record is pe
 
 `standards` reads the authoring root at `standards/` where it exists and the installed copy at `.claude/standards/` otherwise. The authoring root wins because the installed tree is generated from it in the toolkit, where a fix written to the copy is discarded by the next regen. A project that consumed the corpus holds only the second, so one precedence serves both. The walk stays flat, matching install and the catalog, so `standards/bundled/` is out of range: its members are named for the skill that reads them rather than for a path they govern.
 
-Nothing fires it automatically. The four record folders are gitignored, so the standards-audit hook exits early on them and any check reading changed files from git never lists one. The corpus is tracked and still unreached, since the markdown audit reads content across the files git lists and rules on no filename. The verb runs at the moment a session claims the record is finished, which is the same placement `aitk tasks validate` takes over the board.
+Nothing fires it automatically. The five record folders are gitignored, so the standards-audit hook exits early on them and any check reading changed files from git never lists one. The corpus is tracked and still unreached, since the markdown audit reads content across the files git lists and rules on no filename. The verb runs at the moment a session claims the record is finished, which is the same placement `aitk tasks validate` takes over the board.
 
 ### What each kind checks
 
-| Kind         | What it reports                                                                                                                                                                                                                       |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, and a question carrying no suggestion or no answer slot    |
-| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse |
-| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                            |
-| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part       |
-| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs        |
+| Kind         | What it reports                                                                                                                                                                                                                                                                                                  |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, and a question carrying no suggestion or no answer slot                                                                               |
+| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                            |
+| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                       |
+| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part                                                                                  |
+| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs                                                                                   |
+| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal |
 
 The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
 

package/docs/ai-workflow.md

@@ -89,7 +89,7 @@ The plan's shape is fixed by `.claude/standards/plan.md`: the section list, the
 
 An execution that picks other than the suggestion rewrites the `- Suggested:` line as `overridden at execution to <pick>,` followed by the measurement that moved it, and leaves the slot blank. That fixed phrase is how a reader of the archived plan tells an override from a suggestion the execution accepted, since an authored suggestion often carries a number of its own. The same deviation takes one line in the open task's `## Findings`, which is the register that survives the plan being archived. A deviation from a question somebody already answered goes back to whoever answered it instead, since a filled slot is a decision already made.
 
-`aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, and `memory`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all four folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
+`aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
 `aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Eight of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, and `tasks`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
 
@@ -278,8 +278,9 @@ This section is the corpus the coverage claim is measured against: every name `a
 | -------------------------- | ------------------------------------------------------------------------------ |
 | `aitk:toolkit-cli`         | Before a sync or install, to learn what it overwrites, merges, or leaves alone |
 | `aitk:youtube-transcripts` | When a video transcript is wanted in the repo as context                       |
+| `aitk:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress     |
 
-Both rows answer a question rather than mark a point in a project's life, so a phase above would send a reader to the wrong group.
+Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 
 ## Feedback routing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.99.1",
+  "version": "0.100.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/records/backup.ts

@@ -10,9 +10,10 @@ import { gitEnv } from '@/git-env'
  * enclosing repository already. The list is spelled out rather than read off
  * that group so adding an ignore entry cannot silently enlarge the payload.
  *
- * `RECORD_KINDS` in `validate.ts` overlaps this on four names and carries one
+ * `RECORD_KINDS` in `validate.ts` overlaps this on five names and carries one
  * more that no backup reaches. The two lists differ on purpose: one is what a
- * standard governs, this is what a disk loss would take.
+ * standard governs, this is what a disk loss would take, and `standards` is
+ * tracked so a backup would carry a second copy of committed files.
  */
 export const BACKED_FOLDERS = [
   'groundwork',
@@ -23,6 +24,7 @@ export const BACKED_FOLDERS = [
   'review',
   'task-archive',
   'tasks',
+  'teach',
 ] as const
 
 /** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */

package/src/records/validate.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
@@ -10,6 +10,7 @@ export const RECORD_KINDS = [
   'intake',
   'memory',
   'standards',
+  'teach',
 ] as const
 
 export type RecordKind = (typeof RECORD_KINDS)[number]
@@ -29,6 +30,7 @@ const FOLDERS_BY_KIND: Readonly<Record<RecordKind, readonly string[]>> = {
   intake: [join('.claude', 'intake')],
   memory: [join('.claude', 'memory')],
   standards: ['standards', join('.claude', 'standards')],
+  teach: [join('.claude', 'teach')],
 }
 
 /**
@@ -106,7 +108,7 @@ export function isRecordKind(value: string): value is RecordKind {
 /**
  * Whether a kind's folder is shared session scratch at the main worktree root.
  *
- * The four record folders are, so every session validates the records every
+ * The five record folders are, so every session validates the records every
  * other session reads. The corpus is tracked instead, so a linked worktree holds
  * its own edited copy, and defaulting that kind to the main root would report on
  * a tree the session never touched and say nothing about which one it read.
@@ -566,6 +568,174 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
   return [...findings, ...perCluster.flat()]
 }
 
+const TEACH_MISSION = 'MISSION.md'
+const TEACH_RESOURCES = 'RESOURCES.md'
+const TEACH_GLOSSARY = 'GLOSSARY.md'
+const TEACH_REFERENCE = 'reference'
+const TEACH_RECORDS = 'learning-records'
+
+const TEACH_SUCCESS = /^##[ \t]+Success looks like[ \t]*$/
+const WORKSPACE_NAME = /^\d{2}-[a-z0-9]+(-[a-z0-9]+)*$/
+const NUMBERED_RECORD = /^\d{4}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
+/**
+ * A kebab slug that does not open with an ordinal. The lookahead rejects a
+ * leading run of digits followed by a hyphen and nothing else, so a subject
+ * whose own name starts with a digit still passes.
+ */
+const REFERENCE_NAME = /^(?!\d+-)[a-z0-9]+(-[a-z0-9]+)*\.md$/
+
+/** The two fields every markdown file in a workspace carries. */
+async function checkTeachFile(
+  dir: string,
+  slug: string,
+  file: string,
+  subject: string,
+): Promise<Finding[]> {
+  const frontmatter = parseFrontmatter(await readFile(join(dir, file), 'utf8'))
+
+  const missing = ['title', 'description'].filter(
+    (field) => !readField(frontmatter, field),
+  )
+
+  if (missing.length === 0) return []
+
+  return [
+    finding(
+      'frontmatter-incomplete',
+      slug,
+      subject,
+      `carries no ${missing.join(' and no ')}.`,
+    ),
+  ]
+}
+
+/**
+ * One markdown subfolder of a workspace. `lessons/` and `assets/` are never
+ * reached, because a lesson is generated markup carrying no frontmatter and a
+ * walk over it would report every one as malformed.
+ */
+async function checkTeachSubfolder(
+  dir: string,
+  slug: string,
+  folder: string,
+  name: RegExp,
+  message: string,
+): Promise<Finding[]> {
+  const path = join(dir, folder)
+
+  // Tested as a directory rather than for presence. Every other walk in this
+  // module takes its path from `listFolders`, and this one is built from a
+  // fixed name, so a workspace holding a plain file called `reference` would
+  // reach `readdir` and take the whole run down with `ENOTDIR`.
+  if (!statSync(path, { throwIfNoEntry: false })?.isDirectory()) return []
+
+  const files = await listMarkdown(path)
+
+  const malformed = files
+    .filter((file) => !name.test(file))
+    .map((file) =>
+      finding('name-malformed', slug, `${folder}/${file}`, message),
+    )
+
+  const perFile = await Promise.all(
+    files.map((file) => checkTeachFile(path, slug, file, `${folder}/${file}`)),
+  )
+
+  return [...malformed, ...perFile.flat()]
+}
+
+async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
+  const findings: Finding[] = []
+
+  if (!WORKSPACE_NAME.test(slug)) {
+    findings.push(
+      finding(
+        'name-malformed',
+        slug,
+        slug,
+        'is not named NN-<topic> with a two-digit ordinal, so a listing sorts alphabetically rather than by when each workspace opened.',
+      ),
+    )
+  }
+
+  const files = await listMarkdown(dir)
+
+  if (!files.includes(TEACH_MISSION)) {
+    findings.push(
+      finding(
+        'index-missing',
+        slug,
+        TEACH_MISSION,
+        'is absent, so the workspace states no subject and no success to finish against.',
+      ),
+    )
+  }
+
+  for (const required of [TEACH_RESOURCES, TEACH_GLOSSARY]) {
+    if (!files.includes(required)) {
+      findings.push(
+        finding(
+          'section-missing',
+          slug,
+          required,
+          'is required and the workspace carries no such file.',
+        ),
+      )
+    }
+  }
+
+  const perFile = await Promise.all(
+    files.map((file) => checkTeachFile(dir, slug, file, file)),
+  )
+  findings.push(...perFile.flat())
+
+  if (files.includes(TEACH_MISSION)) {
+    const text = await readFile(join(dir, TEACH_MISSION), 'utf8')
+
+    if (!hasOpeningDate(parseFrontmatter(text)?.raw ?? '')) {
+      findings.push(
+        finding(
+          'date-malformed',
+          slug,
+          TEACH_MISSION,
+          'carries no date field as YYYY-MM-DD, so the workspace states no opening day.',
+        ),
+      )
+    }
+
+    if (
+      !linesOutsideFences(text).some((line) => TEACH_SUCCESS.test(line.trim()))
+    ) {
+      findings.push(
+        finding(
+          'section-missing',
+          slug,
+          '## Success looks like',
+          'is absent, so the mission names no observable thing the learner will be able to do.',
+        ),
+      )
+    }
+  }
+
+  return [
+    ...findings,
+    ...(await checkTeachSubfolder(
+      dir,
+      slug,
+      TEACH_REFERENCE,
+      REFERENCE_NAME,
+      'is not named <slug>.md as a kebab slug opening with no ordinal, so a page looked up rather than worked through implies an order no reader follows.',
+    )),
+    ...(await checkTeachSubfolder(
+      dir,
+      slug,
+      TEACH_RECORDS,
+      NUMBERED_RECORD,
+      'is not numbered NNNN-<slug>.md, so the records carry no read order.',
+    )),
+  ]
+}
+
 const MEMORY_INDEX = 'index.md'
 const MEMORY_FIELDS = ['title', 'description', 'category'] as const
 
@@ -872,6 +1042,22 @@ export function checkStandard(name: string, text: string): Finding[] {
   return [...findings, ...checkStandardName(name, scope.statement)]
 }
 
+/**
+ * The three kinds whose records are folders rather than files. Keyed by kind so
+ * a seventh arrives as an entry here and the compiler names the walk it owes,
+ * where a ternary chain would silently fall through to whichever branch is last.
+ */
+const FOLDER_CHECK: Readonly<
+  Record<
+    Exclude<RecordKind, 'plans' | 'memory' | 'standards'>,
+    (dir: string, slug: string) => Promise<Finding[]>
+  >
+> = {
+  groundwork: checkTrack,
+  intake: checkDump,
+  teach: checkWorkspace,
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -939,7 +1125,7 @@ export async function validateRecords(
   }
 
   const folders = await listFolders(dir)
-  const check = kind === 'groundwork' ? checkTrack : checkDump
+  const check = FOLDER_CHECK[kind]
   const perFolder = await Promise.all(
     folders.map((slug) => check(join(dir, slug), slug)),
   )

package/standards/index.md

@@ -26,5 +26,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
+- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/teach.md

@@ -0,0 +1,155 @@
+---
+title: Teach reference
+description: Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
+---
+
+# Teach reference
+
+Applies to a learning workspace at `.claude/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
+
+The folder is gitignored. Its markdown half is written in a format the authoring gates read, so a page promoted out of it later needs no conversion.
+
+## Scope
+
+Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats.
+
+Does not govern:
+
+- What a lesson teaches, how it sequences difficulty, and what makes one worth returning to, which belong to the surface driving the workspace
+- Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
+- One question measured in depth before anyone can plan against it: `groundwork.md`
+- A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- When a workspace opens at all, and the procedure that runs one, which belong to the surface driving it
+
+## What a working workspace looks like
+
+A workspace works when a session returning after weeks can resume from the folder alone:
+
+- Which subject is being learned, and what will the learner be able to do when the mission is finished?
+- Which sources stand behind the material, and which were found and never opened?
+- What has the learner already been through, and what did they get wrong?
+- Which pages here are durable reference material, and which are disposable?
+
+A workspace failing these is non-conforming even when it satisfies every shape rule below.
+
+## Folder name
+
+- Name the folder `<nn>-<topic>`, a two-digit zero-padded ordinal followed by a kebab-case topic slug.
+- Take the ordinal from the highest one already present, incremented. A listing then sorts by when each workspace opened rather than alphabetically.
+- Use two digits on the folder and four inside it. A person opens far fewer workspaces than one workspace holds lessons.
+- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+
+## Layout
+
+| Path                  | Holds                                                  | Required |
+| --------------------- | ------------------------------------------------------ | -------- |
+| `MISSION.md`          | The subject, the learner's starting point, and success | Always   |
+| `RESOURCES.md`        | Sources read and sources found but not opened          | Always   |
+| `GLOSSARY.md`         | Terms the subject defines, one entry each              | Always   |
+| `NOTES.md`            | Session scratch that belongs to no other file          | Optional |
+| `reference/<slug>.md` | Durable reference pages, the promotable half           | Optional |
+| `learning-records/`   | Numbered records of what the learner was taken through | Optional |
+| `lessons/`            | Numbered lessons, generated and disposable             | Optional |
+| `assets/`             | Files several lessons share, including the stylesheet  | Optional |
+
+Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, `reference/`, and `learning-records/`. A lesson is generated markup that nothing downstream cites, so this standard fixes its filename and its location and says nothing about what it contains.
+
+## Frontmatter
+
+Every markdown file carries `title` and `description`. `MISSION.md` carries one field the others do not.
+
+- `title` (required): what the file covers, in sentence case
+- `description` (required): one line naming what a reader gets from it
+- `date` (required, `MISSION.md` only): the day the workspace opened, as `YYYY-MM-DD`
+
+Date the workspace once rather than every file. A per-file date leaves every other file stale the first time one is edited, and the opening date never rots.
+
+## File naming
+
+- Number a lesson and a learning record `0001` upward, as `<nnnn>-<slug>.html` and `<nnnn>-<slug>.md`. The number is read order and never changes.
+- Name a reference page for its subject alone, with no number. A reference page is looked up rather than worked through, so an ordinal on one implies an order no reader follows.
+- Keep one shared stylesheet under `assets/` and link it from every lesson. A lesson restating its own styles makes a workspace read as a pile of one-offs rather than as one course.
+
+## MISSION.md
+
+Fixes what the workspace is for. Everything else in the folder answers to it.
+
+- A one-line statement of the subject
+- A `## Starting point` section stating what the learner already knows, so difficulty has a floor to sit above
+- A `## Success looks like` section listing specific observable things the learner will be able to do
+- A `## Out of scope` section naming what this workspace deliberately does not cover
+
+Write each success line as something a learner can be asked to do rather than something they will understand. A line nobody can test is a line nothing can report progress against.
+
+## Learning records
+
+One record per session the learner worked through, holding what happened rather than what was taught.
+
+- The lessons covered, by number
+- What the learner retrieved correctly without help
+- What they got wrong, and what the wrong answer was
+- What to revisit, and roughly when
+
+Record the wrong answer rather than the fact of an error. A wrong answer names the misconception, and the count alone names nothing.
+
+## GLOSSARY.md
+
+One entry per term the subject defines, sorted alphabetically.
+
+- Lead each entry with the term as a bolded span, then the definition in one or two sentences
+- Define the term without using it
+- Name the lesson or reference page where the term first appears
+- Keep an entry to the meaning. Worked detail belongs on a reference page.
+
+## RESOURCES.md
+
+Splits what was read from what was found.
+
+- List every source that stands behind the material, each with a link
+- List under a leads heading any source found and not opened, and never cite one
+- Say which claims in the workspace rest on which source
+
+A source found and not read is listed as a lead because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later session searching for what this one already surfaced.
+
+## Conventions
+
+- Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
+- Keep a reference page free of the learner. A page carrying a second person or a quiz is a lesson wearing the wrong extension, and it cannot be promoted.
+- Revise a file the subject has moved under rather than appending a second version narrating the change.
+
+## Anti-patterns
+
+- **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
+- **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
+- **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
+- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
+- **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
+
+## Template
+
+```markdown
+---
+title: <Subject>
+description: <one line naming what a learner gets from this workspace>
+date: <YYYY-MM-DD>
+---
+
+# <Subject>
+
+<One line stating the subject.>
+
+## Starting point
+
+<What the learner already knows.>
+
+## Success looks like
+
+- <a specific thing the learner will be able to do>
+- <a specific thing the learner will be able to do>
+
+## Out of scope
+
+- <what this workspace deliberately does not cover>
+```