@erclx/aitk 0.103.0 → 0.104.1

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.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -227,6 +227,10 @@ A board carrying one task written `../plans/x.md` and another written `.claude/p
 
 Exclude the closing task explicitly. It sits on the board and cites the plan itself, so a scan that counts it never reaches zero and no plan is ever archived.
 
+`aitk tasks plan-citations <stem> --json` answers this same question, and the archive gate already reads it. This body states the rule anyway rather than calling the verb, because a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes, so a target whose installed `aitk` predates the verb gets no record back and routes on nothing. Measured against the `claude:docs` `board-sweep` arm, where calling the verb archived neither plan and created no `.claude/plans-archive/`.
+
+Nothing in the exit code reports that. Branch on the record's `ok` and `reason` fields and never on the exit, which is the rule every task verb already carries: 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, and one measured here masks every non-zero exit rather than only an absent verb. The binary itself exits 1 for an unknown subcommand and 1 for an ordinary refusal alike. Switching this body to the verb needs a release that carries it and a read of the record rather than the exit, which together retire the duplication.
+
 A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.claude/plans/` is gitignored, so that retarget would be the only record and there is nothing to recover it from.
 
 - Target resolves inside `.claude/plans/`, the file exists, and no other task file cites it: create `.claude/plans-archive/`, move the file there under its original name, overwriting any file already sitting at that name. Then rewrite the task file's `Plan:` line to the archive path, so a completed task still leads to the reasoning behind it.

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/tasks.md

@@ -24,6 +24,8 @@ aitk tasks archive --pull-request 673 --json
 
 Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `plan-unswept`, or `bad-input`.
 
+`plan-unswept` fires on the last task pointing at a live plan, never on every task pointing at one. The gate counts the other live tasks whose `Plan:` line resolves onto the same file, so a plan several tasks share archives its tasks freely and only the final one is held until `claude-docs` sweeps the plan. Reading the folder alone refused all of them, which deadlocked the board against a sweep correctly declining to move a plan another live task cites.
+
 `bad-input` covers a malformed command line, which all three task verbs answer the same way. It is separate from `ambiguous` and `no-match` because those describe the board, and a caller that passed two selectors would otherwise be sent to repair a task citation that is fine.
 
 The board is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree archives against the same board every other session reads.
@@ -34,6 +36,27 @@ Skills branch on the reason rather than on the exit code:
 aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
 ```
 
+## Plan citations
+
+`aitk tasks plan-citations <stem>` answers where a task's plan sits and which other live tasks hold it. It reports and never writes.
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `location`, one of `unstated`, `live`, `archived`, or `outside`, and `citedBy`, the other live tasks whose `Plan:` line lands on the same file. Exit codes: `0` read, `1` refused with `no-board` or `no-match`.
+
+`aitk tasks archive` gates on this same answer, so a caller wanting the count reads it here rather than scanning the board. The `claude-docs` plans sweep is the exception and still states the rule in its own body, because a plugin skill reaches a target on merge while the CLI reaches one on release, so a sweep calling a verb the installed `aitk` predates gets no record back and archives nothing.
+
+Branch on `reason` rather than on the exit code, which is the rule the archive section above already states and which this verb needs for a second reason. An operator's shell profile may wrap `aitk` in a function that runs the binary and then another command and takes the second status, which masks every non-zero exit rather than only an absent verb. The binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike, so the record is the only signal that survives the wrapper.
+
+A `live` location with an empty `citedBy` is the sweep to run. One whose `citedBy` names a sibling is a plan several tasks share, which the sweep leaves alone and the archive gate lets through.
+
+```bash
+aitk tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
+```
+
 ## Pull request
 
 `aitk tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.
@@ -106,7 +129,11 @@ A backlog line is a bullet carrying a link to a sibling task, since the backlog
 
 The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
 
-The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or closing every outcome, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+
+A closed outcome is not the fact the dependency half needs. The ship chain marks outcomes as its first step and opens the pull request several steps later, so a check reading the checkbox reports the row settled while the branch is still in review. A live task therefore settles the row only once it closed every outcome and carries a `Pull request:` line the trunk holds. One that names no pull request, and one whose number no trunk ref could answer for, land in the untested array below rather than being settled or left silent.
+
+The trunk is read as the clone already holds it, `origin/main` first and local `main` behind it, and no run fetches. A validate runs several times a sweep and a fetch per run is a cost this command does not carry, so a clone behind its remote under-reports rather than claiming work landed.
 
 Both halves gate on a citation inside the `Waiting on` cell, never on the columns beside it. The board format gives a collision cell the file held by the running task, so a row whose cell names no file was parked by something else, and testing its Touches column instead reports a cleared collision on a row no collision ever parked while counting that row as re-tested. A cited task is a bare sibling link, the way the Task column spells one, so a pointer into another folder names a plan rather than a task and settles nothing. A cited task carrying no outcome box settles nothing either, since a file the check could not parse is not evidence of a finished one.
 

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/docs/ai-workflow.md

@@ -105,11 +105,11 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `.claude/memory/` carries the same arrangement, its own hook regenerating `index.md` from each entry's `title`, `description`, and `category`. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
 
-`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every row and task file map one to one, no task sits in two groups, and no two rows marked ready touch the same file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task has closed and one whose cited file nothing running still holds. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, which is where the three kinds resting on a person's judgment land. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
+`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
 `aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
-Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
+Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
 
 Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `aitk:claude-autoship` or `aitk:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
 

package/package.json

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

package/src/commands/tasks.ts

@@ -1,6 +1,12 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
-import { type ArchiveOutcome, archiveTask } from '@/tasks/archive'
+import {
+  type ArchiveOutcome,
+  archiveTask,
+  type CitationOutcome,
+  type PlanCitations,
+  planCitations,
+} from '@/tasks/archive'
 import {
   type CloseOutcome,
   closeOutcomes,
@@ -42,6 +48,11 @@ interface ValidateCommandOptions {
   readonly root?: string
 }
 
+interface CitationsCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface PullRequestCommandOptions {
   readonly json?: boolean
   readonly plan?: string
@@ -126,6 +137,41 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(opts)
     })
 
+  tasks
+    .command('plan-citations')
+    .description('Report where a task plan sits and which live tasks hold it')
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Locations:',
+        '  unstated  the task carries no Plan: line',
+        '  live      the target resolves inside .claude/plans/',
+        '  archived  the target resolves inside .claude/plans-archive/',
+        '  outside   the target resolves somewhere else',
+        '',
+        'Exit codes:',
+        '  0  the citations were read',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It reports and never writes. A live plan whose citedBy list is empty',
+        'is the sweep to run, and one a sibling still holds is left alone.',
+        'The archive gate reads the same answer, so neither can drift.',
+        '',
+        'Examples:',
+        '  aitk tasks plan-citations v28.1-trigger-escalation',
+        '  aitk tasks plan-citations v28.1-trigger-escalation --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: CitationsCommandOptions) => {
+      process.exitCode = await runCitations(task, opts)
+    })
+
   tasks
     .command('pull-request')
     .description('Record a pull request number on the task a branch closes')
@@ -426,6 +472,67 @@ async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   return reportValidation(outcome, opts.json ?? false, root)
 }
 
+async function runCitations(
+  task: string,
+  opts: CitationsCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await planCitations(root, task)
+
+  return reportCitations(outcome, opts.json ?? false, root)
+}
+
+function reportCitations(
+  outcome: CitationOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('aitk tasks plan-citations')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('aitk tasks plan-citations')
+  logStep(outcome.stem)
+  logInfo(describeCitations(outcome))
+  outro()
+
+  return 0
+}
+
+function describeCitations(outcome: PlanCitations): string {
+  if (outcome.location === 'unstated') return 'carries no Plan: line.'
+
+  if (outcome.location === 'archived') {
+    return `points at ${outcome.target}, which an earlier sweep already archived.`
+  }
+
+  if (outcome.location === 'outside') {
+    return `points at ${outcome.target}, which resolves outside both plans folders.`
+  }
+
+  if (outcome.citedBy.length === 0) {
+    return `is the last live task citing ${outcome.target}, so the sweep may archive it.`
+  }
+
+  return `shares ${outcome.target} with ${outcome.citedBy.join(', ')}, so the sweep leaves it.`
+}
+
 function reportValidation(
   outcome: ValidateOutcome,
   emitJson: boolean,

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.',
         ),
       )