@erclx/aitk 0.103.0 → 0.104.1

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),
   }
 }
 

package/standards/tasks.md

@@ -132,7 +132,11 @@ Add no fourth readiness group in place of this file. The three group names are t
 
 ## Validation
 
-`aitk tasks validate` reads the columns above and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a task file reached by neither surface, a task on both surfaces or in two groups, and two `## Run now` rows touching a path in common. It also re-takes the two blocker kinds a command can settle, reporting a parked row whose cited task is archived or has closed every outcome and one whose cited file nothing under `## Run now` still holds. Both halves read a citation out of the cell rather than parsing it into fields, and a row citing neither is reported as untested, which is where the three kinds resting on a person's judgment land. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+`aitk tasks validate` reads the columns above and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a task file reached by neither surface, a task on both surfaces or in two groups, and two `## Run now` rows touching a path in common. It also re-takes the two blocker kinds a command can settle, reporting a parked row whose cited task reached the trunk and one whose cited file nothing under `## Run now` still holds. Both halves read a citation out of the cell rather than parsing it into fields, and a row citing neither is reported as untested, which is where the three kinds resting on a person's judgment land. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+
+A cited task is settled by being archived, or by closing every outcome and carrying a `Pull request:` line the trunk holds. The closed checkbox alone settles nothing, because the ship chain marks outcomes as its first step and opens the pull request several steps later, so a row read off the checkbox reports settled while the branch is still in review. A task that closed every outcome and names no pull request, and one whose pull request the run could not read against the trunk, are both reported as untested. Degrading either back to the checkbox would reproduce the defect under a name claiming it was fixed.
+
+The trunk is read as the clone already holds it, `origin/main` first and local `main` behind it, and no run fetches. A validate happens several times a sweep and a fetch per run is a cost this check does not carry, so a clone behind the remote under-reports rather than claiming work landed.
 
 A task file is accounted for when a row on `priority.md` or a line on `backlog.md` names it, and reported when neither does. One check across both surfaces is what lets a task move between them without the move looking like a dropped file, and a task named by both is reported for the same reason a task in two groups is: it claims two things about itself and only one of them can hold. A project carrying no `backlog.md` is read as an empty backlog rather than refused, which leaves the one-to-one mapping this check ran before the second surface existed.
 
@@ -252,8 +256,16 @@ Archiving a task does not archive its plan. `claude-docs` owns the plans sweep a
 
 The row is matched by the link in its first cell rather than by a pattern against the whole line. A row names the task it is about in the first cell, so a link anywhere after that is a reference, such as a blocker pointing at what it waits on. Matching the line would delete the referring task's row too, on a board that is gitignored and has nothing to recover it from.
 
-Sweep the plan before archiving the task. The sweep finds its work by scanning the live folder, so a task archived first is beyond its reach for good, and the plan is left with no live task citing it and an archived task pointing at a path nothing will retarget. The archive refuses a task whose `Plan:` line still resolves inside `.claude/plans/` for that reason, which puts the ordering under a gate rather than under a convention the unattended caller cannot follow.
+Sweep the plan before archiving the task. The sweep finds its work by scanning the live folder, so a task archived first is beyond its reach for good, and the plan is left with no live task citing it and an archived task pointing at a path nothing will retarget. The archive refuses the last task pointing at a live plan for that reason, which puts the ordering under a gate rather than under a convention the unattended caller cannot follow.
+
+The gate counts the other live tasks citing the same plan rather than reading which folder the plan sits in. A plan several tasks share stays in the live folder by design, because the sweep is correct to leave a plan another live task still cites, so a gate reading the folder alone refuses every one of those tasks and the board and the sweep block each other with neither in the wrong. Counting the citations asks the question the gate means: a plan nothing else holds is one the sweep has yet to reach, and a plan a sibling still holds is one the sweep already decided about.
+
+The count resolves the target against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file and one plan two tasks spelled differently counts once. `aitk tasks plan-citations` exposes that count for a caller that wants it, and the gate reads it.
+
+The `claude-docs` sweep states the rule rather than calling that verb, which is a duplication accepted with a reason rather than an oversight. A skill reaches a target the moment it merges and the CLI reaches one only when a release publishes, so a body calling a verb the installed `aitk` predates gets no record back and sweeps nothing. The two spellings therefore have to agree by hand until a release carries the verb, and the failure they guard against is a plan stranded by the form its citation was written in.
+
+A caller reads the outcome off the record's `reason` field and never off the exit code. An operator's shell profile may wrap `aitk` in a function that runs the binary and then another command, taking its status from the second, which masks an ordinary refusal exactly as it masks an absent verb.
 
-That gate resolves the target against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file. `claude-docs` reads the line the same way, and two halves of one ordering that parsed it differently would leave a plan stranded by the form it was written in.
+Surviving a shared plan is not the same as sanctioning one. `standards/plan.md` puts one concern in one plan file, so a plan serving several tasks is a shape to correct rather than to build on, and the gate only stops it from deadlocking the board.
 
 A task with an open outcome stays on the board. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. The sweep is gated on the same condition, so archiving around an open outcome also leaves the plan behind.