@erclx/aitk 0.103.0 → 0.104.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.103.0",
+  "version": "0.104.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -40,7 +40,7 @@ From a linked worktree the file-editing tools refuse every path under the main r
 
 A topic the listing already carries is a resume, and anything else is a new workspace. An invocation asking to promote is neither: read the named workspace through the listing and go to Step 6, which teaches nothing and writes no lesson.
 
-On a resume, run `aitk teach list <topic> --json` for the files behind each count, then 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 resume, run `aitk teach list <topic> --json` for the files behind each count, then read the highest-numbered learning record and `GLOSSARY.md`. Those carry where the learner stopped and what they got wrong. The listing record carries `success`, the mission's success lines, which are the exit criteria this workspace is finished against. Report them 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.
 
@@ -80,9 +80,27 @@ Open with retrieval on what the last session got wrong, before anything new. A l
 
 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 lesson is a self-contained page carrying its own quiz and the feedback for each answer. It links one shared stylesheet rather than restating styles, and it is disposable and 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.
 
+Resolve the lesson before writing it, rather than composing its name or its quiz order by hand:
+
+```bash
+aitk teach lesson <topic> --json \
+  --slug <kebab slug for what this lesson covers> \
+  --questions <how many questions the quiz carries> \
+  --options <how many options each question carries>
+```
+
+It writes nothing and reports four things:
+
+- `lesson`, the numbered path the lesson takes. Write it there.
+- `stylesheet` with `stylesheetExists` and `stylesheetHref`. Write the stylesheet only when it reports absent, which is the first lesson in the workspace. Every lesson after that links the file already on disk and adds to it rather than replacing it, since overwriting discards what the last lesson put there.
+- `success`, the mission's success lines, carried here so Step 5 needs no second read.
+- `quiz`, one entry per question, carrying `order` and `answer`.
+
+Write the correct option first, then present the options in the order `order` reports, reading it as authored indices where `0` is the correct one. Take the order as given. Position drawn here rather than chosen is the whole reason the verb exists, and a lesson that reorders on its own judgment puts the answer back in the first slot.
+
 Add every term the lesson defines to `GLOSSARY.md` through the verb, which places the entries alphabetically in the shape the standard fixes:
 
 ```bash
@@ -101,7 +119,7 @@ Write `learning-records/<nnnn>-<slug>.md` before the session ends, carrying the
 
 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.
+Then restate the mission's success lines with what is now met, reading them from the `success` the lesson verb already reported rather than from `MISSION.md` by eye. Report each line as met or not met, and name what the learner did that meets it. A mission whose lines are all met is finished, and saying so is what closes a workspace.
 
 ## Step 6: propose where the durable half belongs
 

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

@@ -13,6 +13,7 @@ A workspace accumulates lessons over weeks. The learner reads them as one body o
 
 - 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.
+- Add to that stylesheet rather than replacing it. The lesson writing it is rarely the lesson that needs it changed, and a rewrite drops what every earlier lesson links it for.
 - 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.
 
@@ -39,11 +40,17 @@ Every element competes with the material for attention.
 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
+- Write the correct option first and let the ordering verb place it. Position is not the author's to pick: an author who varies it by hand still varies it by judgment, and the judgment settles on the first slot.
 - 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
 
+## Tokens travel with the course
+
+A lesson carries its own values in the shared stylesheet rather than reading a host project's. A workspace runs in any project and most carry no token record at all, so a lesson inheriting one is a lesson that renders unstyled wherever the record is absent, with nothing reporting it.
+
+Pick values the material needs rather than values the project happens to hold. Inheriting is worth offering as something a learner asks for once, and it is the wrong default in every project that cannot answer.
+
 ## 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.

package/docs/agents/index.md

@@ -26,4 +26,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
-- [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, the refusal reasons, and why every write here runs through a verb
+- [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb

package/docs/agents/teach.md

@@ -1,6 +1,6 @@
 ---
 title: Teach
-description: Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, the refusal reasons, and why every write here runs through a verb
+description: Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
 ---
 
 # Teach
@@ -102,6 +102,33 @@ A term already defined is refused rather than replaced. A definition the subject
 
 The entry lands as the standard's shape, leading with the term as a bolded span. A definition not ending in sentence punctuation is terminated before the citation is appended, so a bare phrase does not run into the sentence naming where the term first appears.
 
+## Lesson
+
+`aitk teach lesson` resolves what the next lesson needs before it is written. It reads and never writes.
+
+```bash
+aitk teach lesson regular-expressions \
+  --slug capture-groups \
+  --questions 3 \
+  --options 4
+```
+
+| Option            | Behavior                                                  |
+| ----------------- | --------------------------------------------------------- |
+| `--slug <kebab>`  | The lesson's own topic, required                          |
+| `--questions <n>` | How many questions the quiz carries, required             |
+| `--options <n>`   | How many options each question carries, defaulting to `4` |
+| `--json`          | Emit a machine-readable record on stdout                  |
+| `--root <path>`   | Teach root, defaulting to the main worktree               |
+
+It reports four things. `lesson` is the numbered path the lesson takes, derived from the highest ordinal already in `lessons/` the way an open derives a workspace ordinal. `stylesheet` names the one file every lesson in the workspace links, with `stylesheetExists` saying whether it is on disk yet and `stylesheetHref` carrying what the lesson's own link element holds. `success` carries the mission's success lines, so a session reports progress against the exit criteria without a second read of `MISSION.md`. `quiz` carries one entry per question.
+
+The stylesheet is reported rather than written. A verb that wrote it on every lesson would discard whatever the last lesson added, and the second lesson in a workspace is the one that needs the file the first one left.
+
+Each `quiz` entry carries `order`, the authored option indices in presentation order where index `0` is the correct answer, and `answer`, the one-based position that answer lands in. Both travel together because a caller deriving the position itself is a caller that can derive it wrongly.
+
+The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.
+
 ## Refusal reasons
 
 | Reason         | Raised when                                                     |
@@ -116,4 +143,4 @@ The entry lands as the standard's shape, leading with the term as a bolded span.
 | `defined`      | A term already carries a glossary entry                         |
 | `bad-input`    | The command line is malformed, before any folder is read        |
 
-A `bad-input` refusal reports the working directory as its root rather than the resolved one, since the command line is rejected before the root is worth resolving.
+A `bad-input` refusal reports the working directory as its root rather than the resolved one, since the command line is rejected before the root is worth resolving. `lesson` raises it for a slug that is not kebab-case, for a quiz carrying no question, and for a question carrying fewer than two options, since a question with one option has nothing to confuse the right answer with.

package/package.json

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

package/src/commands/teach.ts

@@ -1,5 +1,6 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
+import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import {
   defineTerms,
   type ListOutcome,
@@ -57,6 +58,14 @@ interface ResourceCommandOptions {
   readonly root?: string
 }
 
+interface LessonCommandOptions {
+  readonly json?: boolean
+  readonly options?: string
+  readonly questions?: string
+  readonly root?: string
+  readonly slug?: string
+}
+
 interface GlossaryCommandOptions {
   readonly firstSeen?: string
   readonly json?: boolean
@@ -231,6 +240,42 @@ export function register(program: Command): void {
     .action(async (topic: string, opts: GlossaryCommandOptions) => {
       process.exitCode = await runGlossary(topic, opts)
     })
+
+  teach
+    .command('lesson')
+    .description('Resolve what the next lesson needs before it is written')
+    .argument('<topic>', 'Workspace folder or topic, as in regular-expressions')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--slug <kebab>', "The lesson's own topic, as in capture-groups")
+    .option('--questions <n>', 'How many questions the quiz carries')
+    .option('--options <n>', 'How many options each question carries', '4')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Teach root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the lesson was planned',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It writes nothing. It reports the numbered path the lesson takes, the',
+        'shared stylesheet with whether that file exists yet, the mission',
+        'success lines to report progress against, and one option order per',
+        'question.',
+        '',
+        'Write the correct option first and present the options in the order',
+        'reported. Position is drawn here rather than chosen, so an answer',
+        'cannot settle into the first slot.',
+        '',
+        'Examples:',
+        '  aitk teach lesson regular-expressions --slug capture-groups --questions 3 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (topic: string, opts: LessonCommandOptions) => {
+      process.exitCode = await runLesson(topic, opts)
+    })
 }
 
 function collect(value: string, previous: string[]): string[] {
@@ -435,6 +480,43 @@ async function runGlossary(
   )
 }
 
+async function runLesson(
+  topic: string,
+  opts: LessonCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!opts.slug) {
+    return reportRefusal(
+      'aitk teach lesson',
+      badInput('No lesson slug. Pass --slug <kebab>.'),
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  if (!opts.questions) {
+    return reportRefusal(
+      'aitk teach lesson',
+      badInput('No question count. Pass --questions <n>.'),
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = await rootFor(opts.root)
+
+  return reportLesson(
+    await planLesson(root, topic, {
+      slug: opts.slug,
+      questions: Number(opts.questions),
+      options: Number(opts.options ?? '4'),
+    }),
+    emitJson,
+    root,
+  )
+}
+
 function reportRefusal(
   title: string,
   refused: TeachRefused,
@@ -545,6 +627,11 @@ function reportWorkspace(
   logStep(workspace.glossary.length > 0 ? 'Glossary' : 'Glossary (empty)')
   for (const entry of workspace.glossary) logInfo(entry)
 
+  logStep(
+    workspace.success.length > 0 ? 'Exit criteria' : 'Exit criteria (none)',
+  )
+  for (const line of workspace.success) logInfo(line)
+
   if (workspace.missing.length > 0) {
     logStep('Missing a required file')
     logWarn(`no ${workspace.missing.join(' and no ')}`)
@@ -648,3 +735,52 @@ function reportGlossary(
 
   return 0
 }
+
+function reportLesson(
+  outcome: LessonOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk teach lesson', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        path: outcome.path,
+        lesson: outcome.lesson,
+        stylesheet: outcome.stylesheet,
+        stylesheetHref: outcome.stylesheetHref,
+        stylesheetExists: outcome.stylesheetExists,
+        success: outcome.success,
+        quiz: outcome.quiz,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk teach lesson')
+  logStep('Lesson')
+  logInfo(outcome.lesson)
+
+  logStep(outcome.stylesheetExists ? 'Stylesheet' : 'Stylesheet (to write)')
+  logInfo(`${outcome.stylesheet} linked as ${outcome.stylesheetHref}`)
+
+  logStep(outcome.success.length > 0 ? 'Exit criteria' : 'Exit criteria (none)')
+  for (const line of outcome.success) logInfo(line)
+
+  logStep('Option order')
+  for (const question of outcome.quiz) {
+    logInfo(
+      `question ${question.question}: present ${question.order.join(', ')}, correct answer in position ${question.answer}`,
+    )
+  }
+
+  outro()
+
+  return 0
+}

package/src/records/validate.ts

@@ -9,6 +9,7 @@ import {
   TEACH_RECORDS,
   TEACH_REFERENCE,
   TEACH_RESOURCES,
+  TEACH_SUCCESS_HEADING,
   WORKSPACE_NAME,
 } from '@/teach/workspace'
 
@@ -576,7 +577,6 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
   return [...findings, ...perCluster.flat()]
 }
 
-const TEACH_SUCCESS = /^##[ \t]+Success looks like[ \t]*$/
 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
@@ -705,13 +705,15 @@ async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
     }
 
     if (
-      !linesOutsideFences(text).some((line) => TEACH_SUCCESS.test(line.trim()))
+      !linesOutsideFences(text).some(
+        (line) => line.trim() === TEACH_SUCCESS_HEADING,
+      )
     ) {
       findings.push(
         finding(
           'section-missing',
           slug,
-          '## Success looks like',
+          TEACH_SUCCESS_HEADING,
           'is absent, so the mission names no observable thing the learner will be able to do.',
         ),
       )

package/src/sandbox/expect.ts

@@ -209,23 +209,35 @@ export function countMechanicalAssertions(expectation: Expectation): number {
   )
 }
 
+/**
+ * An entry carrying `*` is matched as a glob, so an arm can assert a file whose
+ * name a run derives. Reports the matched path rather than the pattern, since a
+ * pass on `lessons/0001-*.html` says nothing until the name it found is named.
+ */
 function checkPaths(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
-  return expectation.paths.map((path) =>
-    existsSync(join(sandboxDir, path))
-      ? { ok: true, message: `exists: ${path}` }
-      : { ok: false, message: `missing: ${path}` },
-  )
+  return expectation.paths.map((path) => {
+    const written = writtenUnder(path, sandboxDir)
+
+    return written
+      ? { ok: true, message: `exists: ${written}` }
+      : { ok: false, message: `missing: ${path}` }
+  })
 }
 
 /**
- * An entry carrying `*` is matched as a glob, which is what lets an arm forbid
- * a file whose name a run derives rather than fixes. Pinning one spelling of a
- * derived name passes vacuously against every other spelling, which reads as
- * coverage the arm does not have. Returns the offending path so a failure names
- * the file the run wrote rather than the pattern that caught it.
+ * The first file an entry matches, or undefined when it matches none. An entry
+ * carrying `*` is matched as a glob, which is what lets an arm name a file whose
+ * name a run derives rather than fixes. Pinning one spelling of a derived name
+ * passes vacuously against every other spelling, which reads as coverage the arm
+ * does not have.
+ *
+ * Returning the match rather than a boolean is what lets a result name the file
+ * the run wrote instead of the pattern that found it. A glob matching several
+ * files answers with one of them in no fixed order, so an arm asserting content
+ * through a glob seeds a folder holding one.
  */
 function writtenUnder(pattern: string, sandboxDir: string): string | undefined {
   if (!pattern.includes('*')) {
@@ -260,14 +272,18 @@ function checkAbsent(
  * throwing, since an arm may assert content without also listing the path. A
  * pattern that does not compile is a defect in the declaration, so it fails the
  * assertion it belongs to rather than aborting the whole verdict.
+ *
+ * A path carrying `*` resolves to the file it matched, and falls back to itself
+ * when it matched none so the miss is reported against the entry as written.
  */
 function checkContent(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
   return expectation.content.map(({ path, pattern }) => {
-    const full = join(sandboxDir, path)
-    const label = `${path} =~ ${pattern}`
+    const matched = writtenUnder(path, sandboxDir) ?? path
+    const full = join(sandboxDir, matched)
+    const label = `${matched} =~ ${pattern}`
 
     let matcher: RegExp
     try {
@@ -279,6 +295,7 @@ function checkContent(
     if (!existsSync(full) || !statSync(full).isFile()) {
       return { ok: false, message: `no file to match: ${path}` }
     }
+
     if (matcher.test(readFileSync(full, 'utf8'))) {
       return { ok: true, message: `matches: ${label}` }
     }

package/src/teach/lesson.ts

@@ -0,0 +1,180 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  readWorkspace,
+  refuse,
+  TEACH_ASSETS,
+  TEACH_LESSONS,
+  TEACH_STYLESHEET,
+  type TeachRefused,
+} from '@/teach/workspace'
+
+/** Four digits inside a workspace, per the standard, because one holds many. */
+const LESSON_WIDTH = 4
+
+/** The ordinal a lesson filename opens with, which fixes its read order. */
+const LESSON_NUMBER = /^(\d{4})-/
+
+const LESSON_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+/** A quiz needs a right answer and at least one thing to confuse it with. */
+const MIN_OPTIONS = 2
+
+export interface QuizOrder {
+  /** One-based, so a report reads the same way the lesson numbers them. */
+  readonly question: number
+  /**
+   * Authored indices in the order the lesson presents them, where the authored
+   * index `0` is the correct answer. The author writes the correct option first
+   * and reads its position back off this list.
+   */
+  readonly order: readonly number[]
+  /** Where the correct answer lands, one-based, so no caller derives it. */
+  readonly answer: number
+}
+
+export interface LessonPlanned {
+  readonly ok: true
+  readonly slug: string
+  /** Relative to the root, so a caller prints a path a reader can open. */
+  readonly path: string
+  readonly lesson: string
+  readonly stylesheet: string
+  /** What the lesson's own `link` element carries, resolved from `lessons/`. */
+  readonly stylesheetHref: string
+  /** False on the first lesson in a workspace, which writes the stylesheet. */
+  readonly stylesheetExists: boolean
+  /** The mission's success lines, reported as the exit criteria they are. */
+  readonly success: readonly string[]
+  readonly quiz: readonly QuizOrder[]
+}
+
+export type LessonOutcome = LessonPlanned | TeachRefused
+
+export interface LessonRequest {
+  readonly slug: string
+  readonly questions: number
+  readonly options: number
+  /**
+   * Injected so a test can assert the shape of an order against a generator it
+   * controls. Every caller outside a test takes the default, which is what
+   * keeps the position of a correct answer off the author's judgment.
+   */
+  readonly random?: () => number
+}
+
+/**
+ * A uniform permutation of `0 .. count - 1` by Fisher-Yates.
+ *
+ * The bias this exists against is the authored order surviving into the
+ * lesson, which puts the correct answer first whenever the author wrote it
+ * first. Drawing the permutation here rather than in a prompt is what makes the
+ * position unguessable from the outside.
+ */
+function shuffled(count: number, random: () => number): number[] {
+  const order = Array.from({ length: count }, (_, index) => index)
+
+  for (let index = count - 1; index > 0; index -= 1) {
+    const pick = Math.floor(random() * (index + 1))
+    const held = order[index]
+    order[index] = order[pick]
+    order[pick] = held
+  }
+
+  return order
+}
+
+/**
+ * One presentation order per question, each carrying where the correct answer
+ * landed. Both halves travel together because a caller deriving the position
+ * itself is a caller that can derive it wrongly.
+ */
+export function orderQuiz(
+  questions: number,
+  options: number,
+  random: () => number = Math.random,
+): QuizOrder[] {
+  return Array.from({ length: questions }, (_, index) => {
+    const order = shuffled(options, random)
+
+    return {
+      question: index + 1,
+      order,
+      answer: order.indexOf(0) + 1,
+    }
+  })
+}
+
+/**
+ * The number the next lesson takes, read off the filenames already there.
+ *
+ * A file whose name carries no ordinal moves nothing, the way a workspace
+ * folder with no ordinal moves no workspace number. Numbering past it would
+ * renumber nothing and skipping it would hide it.
+ */
+function nextLesson(files: readonly string[]): string {
+  const highest = files
+    .map((file) => LESSON_NUMBER.exec(file)?.[1])
+    .filter((ordinal): ordinal is string => ordinal !== undefined)
+    .reduce((carry, ordinal) => Math.max(carry, Number(ordinal)), 0)
+
+  return String(highest + 1).padStart(LESSON_WIDTH, '0')
+}
+
+/**
+ * Everything a lesson needs resolved before it is written: where it goes, which
+ * stylesheet it links and whether that file is already on disk, the mission's
+ * exit criteria, and the order each quiz presents its options in.
+ *
+ * The stylesheet is reported rather than written. Every lesson after the first
+ * reads the one the first wrote, so a verb that rewrote it on every lesson
+ * would discard whatever the last one added.
+ */
+export async function planLesson(
+  root: string,
+  selector: string,
+  request: LessonRequest,
+): Promise<LessonOutcome> {
+  if (!LESSON_SLUG.test(request.slug)) {
+    return refuse('bad-input', `Not a kebab-case slug: ${request.slug}.`, [
+      request.slug,
+    ])
+  }
+
+  if (!Number.isInteger(request.questions) || request.questions < 1) {
+    return refuse(
+      'bad-input',
+      'A lesson carries at least one question. Pass --questions <n>.',
+    )
+  }
+
+  if (!Number.isInteger(request.options) || request.options < MIN_OPTIONS) {
+    return refuse(
+      'bad-input',
+      `A question carries at least ${MIN_OPTIONS} options. Pass --options <n>.`,
+    )
+  }
+
+  const found = await readWorkspace(root, selector)
+  if (!found.ok) return found
+
+  const workspace = found.workspace
+  const lesson = join(
+    workspace.path,
+    TEACH_LESSONS,
+    `${nextLesson(workspace.lessonFiles)}-${request.slug}.html`,
+  )
+  const stylesheet = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+
+  return {
+    ok: true,
+    slug: workspace.slug,
+    path: workspace.path,
+    lesson,
+    stylesheet,
+    stylesheetHref: `../${TEACH_ASSETS}/${TEACH_STYLESHEET}`,
+    stylesheetExists: existsSync(join(root, stylesheet)),
+    success: workspace.success,
+    quiz: orderQuiz(request.questions, request.options, request.random),
+  }
+}

package/src/teach/workspace.ts

@@ -32,6 +32,22 @@ export const TEACH_GLOSSARY = 'GLOSSARY.md'
 export const TEACH_REFERENCE = 'reference'
 export const TEACH_RECORDS = 'learning-records'
 export const TEACH_LESSONS = 'lessons'
+export const TEACH_ASSETS = 'assets'
+
+/**
+ * The one stylesheet every lesson in a workspace links. The name is fixed here
+ * rather than chosen per lesson, because the second lesson has to reach the
+ * file the first one wrote and a name composed twice is a name that can differ.
+ */
+export const TEACH_STYLESHEET = 'course.css'
+
+/**
+ * The mission heading whose list a session reads as exit criteria. The writer,
+ * the reader below, and the record validator all match this one spelling, so a
+ * heading none of them can find fails the validator rather than reading as an
+ * empty list.
+ */
+export const TEACH_SUCCESS_HEADING = '## Success looks like'
 
 /**
  * A workspace folder as the standard names it, capturing the ordinal and the
@@ -79,6 +95,8 @@ export interface WorkspaceDetail extends WorkspaceSummary {
   readonly recordFiles: readonly string[]
   readonly referenceFiles: readonly string[]
   readonly glossary: readonly string[]
+  /** The mission's success lines, which a session reports progress against. */
+  readonly success: readonly string[]
 }
 
 export interface WorkspacesListed {
@@ -141,7 +159,7 @@ export interface OpenRequest {
   readonly date?: string
 }
 
-function refuse(
+export function refuse(
   reason: TeachRefusal,
   message: string,
   detail: readonly string[] = [],
@@ -198,6 +216,30 @@ function glossaryTerms(text: string): string[] {
     .map((line) => line.trim().slice('- '.length))
 }
 
+/**
+ * The mission's success lines, each one an observable thing the learner will be
+ * able to do. A session reads them as exit criteria, so a wrapped entry is
+ * joined back into one line rather than reported as two criteria.
+ *
+ * A mission carrying no such heading yields nothing rather than refusing. The
+ * record validator is what reports the absent section, and a listing that
+ * refused would take the whole workspace down with it.
+ */
+function successLines(text: string): string[] {
+  const lines = text.split('\n')
+  const section = sectionRange(
+    unfenced(text),
+    TEACH_SUCCESS_HEADING,
+    lines.length,
+  )
+
+  if (!section) return []
+
+  return bulletBlocks(lines.slice(section.start, section.end)).map((block) =>
+    block.join(' ').trim().slice('- '.length).replace(/\s+/g, ' ').trim(),
+  )
+}
+
 /** The ordinal a folder name carries, or `NaN` when it carries none. */
 function ordinalOf(slug: string): number {
   const match = WORKSPACE_NAME.exec(slug)
@@ -211,9 +253,11 @@ async function summarize(
 ): Promise<WorkspaceDetail> {
   const match = WORKSPACE_NAME.exec(slug)
   const missionPath = join(dir, TEACH_MISSION)
-  const frontmatter = existsSync(missionPath)
-    ? parseFrontmatter(await readFile(missionPath, 'utf8'))
+  const mission = existsSync(missionPath)
+    ? await readFile(missionPath, 'utf8')
     : undefined
+  const frontmatter =
+    mission === undefined ? undefined : parseFrontmatter(mission)
 
   const glossaryPath = join(dir, TEACH_GLOSSARY)
   const glossary = existsSync(glossaryPath)
@@ -244,6 +288,7 @@ async function summarize(
     recordFiles,
     referenceFiles,
     glossary,
+    success: mission === undefined ? [] : successLines(mission),
   }
 }