@erclx/aitk 0.99.1 → 0.101.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.101.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -109,8 +109,8 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 5. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
 6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
    - Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. That runbook holds the routing, and a summary of it here is a second source that drifts from it.
-7. Dispatch the handback. A pass posting a finding at any severity tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Read that off the counts on the summary line rather than off the heading, since a minors-only pass closes the heading and still owes a dispatch. Re-review when the answer lands, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
-   - Send only above that floor. A minor posts under the same heading and is visibility alone, so a rule keyed on any open finding sends a worker to act on a note
+7. Dispatch the handback. A pass posting a finding at any severity tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Re-review when the answer lands, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
+   - Read the threshold off `claude-pr-review`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send
    - Resolve the target from a fresh session listing at the moment of sending, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour
    - Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
    - Name the skill for the reader to run rather than writing an invocation, which arrives as text

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -34,13 +34,13 @@ Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what
 - MOVED or RESPONSE on a pull request I have already reviewed: run the aitk:claude-pr-review skill on it immediately, narrow pass. Re-reviews read prior..head and gain nothing from waiting.
 - OPENED, or a pull request with no prior review pass: run the aitk:claude-pr-review skill on it. A draft counts, since every pull request here opens as one and skipping drafts skips everything.
 - SEEN: report it and stop. A pass already covers that head, whether it arrived out of band or before the poll first saw the pull request, so no review follows.
-- STALLED: read the last pass and report what it carried. The pass has sat open for hours with nothing following it, so a worker mid-task is already ruled out and the dispatch either never went out or the session holding it is gone. Confirm and re-send it under the dispatch rule below. A pass carrying only minors is also under the wrong heading, so say so, and dispatch it either way. Do not re-run a review to correct the heading, since a pass on an unchanged head with no response behind it stops by design.
+- STALLED: read the last pass and report what it carried. The pass has sat open for hours with nothing following it, so a worker mid-task is already ruled out and the dispatch either never went out or the session holding it is gone. Confirm and re-send it under the dispatch rule below, whatever grades the pass carried. Do not re-run a review to correct the heading, since a pass on an unchanged head with no response behind it stops by design.
 - CONFLICT: report it and stop. The branch owner rebases, not this session.
 - GONE: report it, then sweep the board by invoking the aitk:claude-orchestrate skill and following its queue-refill sweep.
 - A line starting `poll:`: report it verbatim and treat that pull request as unread this run. It is a failed query, not a state.
 - Nothing changed: say exactly "No movement." and nothing else.
 
-After any pass that posts a finding, at any severity, tell the session holding that branch to run the aitk:claude-address-review skill. Resolve the target by running `aitk sessions list --branch <branch> --json` at that moment, which scopes the match to this repository, then route on how many sessions it returned. Zero: report the invocation for me and dispatch nobody. Exactly one, with the confidence field reading "confirmed": address that name directly. Any other count, any other confidence, or a command that is missing or refuses: fall back to picking from a session listing, open by naming the worktree and branch you believe the reader holds, and ask to be corrected. Two sessions can hold one branch, so read the count rather than the first row. The heading does not decide this: a minors-only pass posts the closed heading and still owes a dispatch, so read the counts on the summary line rather than the heading above them.
+After any pass that posts a finding, at any severity, tell the session holding that branch to run the aitk:claude-address-review skill. Resolve the target by running `aitk sessions list --branch <branch> --json` at that moment, which scopes the match to this repository, then route on how many sessions it returned. Zero: report the invocation for me and dispatch nobody. Exactly one, with the confidence field reading "confirmed": address that name directly. Any other count, any other confidence, or a command that is missing or refuses: fall back to picking from a session listing, open by naming the worktree and branch you believe the reader holds, and ask to be corrected. Two sessions can hold one branch, so read the count rather than the first row. The threshold is stated once in the aitk:claude-pr-review skill and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send.
 ```
 
 ## Reading the output
@@ -53,6 +53,6 @@ The baseline lives at `.claude/.tmp/pr-poll/baseline.txt` under the main worktre
 
 The four review headings the script matches are written by `claude-pr-review` and `claude-address-review`. A project that posts its reviews under different headings edits the three jq filters in the script to match, or every pull request reads as never reviewed.
 
-`STALLED` is the one state the script derives from a heading rather than from a commit or a count, since `claude-pr-review` posts the open heading only for a pass carrying a critical or a should-fix. The heading alone cannot carry it, because an open pass means a dispatch was owed and made, so the ordinary healthy thread is a worker still working. The age of that pass is the third test: the state fires when the open pass covers the head, nothing has followed it, and it is older than the `STALE_AFTER` seconds set at the top of the script. It reports once per entry and fires again after any commit or reply resets the thread. A project whose workers run longer than the default two hours raises that number.
+`STALLED` is the one state the script derives from a heading rather than from a commit or a count, since `claude-pr-review` posts the open heading exactly when a dispatch is owed, per the threshold that skill states. The heading alone cannot carry it, because an open pass means a dispatch was owed and made, so the ordinary healthy thread is a worker still working. The age of that pass is the third test: the state fires when the open pass covers the head, nothing has followed it, and it is older than the `STALE_AFTER` seconds set at the top of the script. It reports once per entry and fires again after any commit or reply resets the thread. A project whose workers run longer than the default two hours raises that number.
 
-What the state does not reach is a dispatch owed on a minor. The dispatch fires on a finding at any severity and the heading closes on a blocking one, so a minors-only pass owes a worker under a closed heading, and this state reads the open heading alone. It therefore catches a stalled blocking finding and never a stalled minor. That is a narrowing rather than a defect, and closing it would mean reading the counts off the summary line, which pins a second string this script does not own.
+The state reaches every stalled dispatch, since one threshold governs the heading and the dispatch alike and a pass carrying anything posts the open heading. A minors-only pass therefore reports here on the same terms as a blocking one, which widens the state from what it caught while the two were split. It stays a heading test rather than a count test, so nothing here pins the summary line, which is a second string this script does not own.

package/claude/skills/claude-orchestrate/scripts/poll.sh

@@ -55,11 +55,11 @@ JQ_REPLY_COUNT='
   ] | length
 '
 
-# `claude-pr-review` posts `## Review` only for a pass carrying a critical or a
-# should-fix, so the heading of the last review is what says whether anything
-# blocks the merge. Taking it as well as the commit is what separates a thread
-# waiting on a worker from one a pass left open owing no dispatch. A project
-# editing the two filters above for its own headings edits this one with them.
+# `claude-pr-review` states the threshold and posts `## Review` exactly when a
+# pass carries a finding, so the heading of the last review is what says whether
+# any work is owed on it. Taking it as well as the commit is what separates a
+# thread waiting on a worker from one nothing is owed on. A project editing the
+# two filters above for its own headings edits this one with them.
 #
 # The age of that review comes out of the same selection, because the heading
 # alone cannot separate the two. Under the rule above an open heading means a
@@ -251,11 +251,12 @@ while read -r n head prior resp merges heading age; do
     [ "$prior" = "$head" ] && [ "$age" -ge "$STALE_AFTER" ]; then
     # Three things at once: the last pass is open, it covers the head so no
     # commit followed it, and the two branches above found no reply either. The
-    # open heading is posted only for a critical or should-fix, so a pass owing
-    # no dispatch left it here. Any two of these describe an ordinary review
-    # waiting on a worker, which is why the age carries the third: without it
-    # every dispatched worker is reported minutes into the work it was sent to
-    # do, and a signal firing on the healthy path is one an operator learns to
+    # open heading is posted exactly when a dispatch is owed, per the threshold
+    # `claude-pr-review` states, so a pass owing one left it here at any grade
+    # it carried. Any two of these describe an ordinary review waiting on a
+    # worker, which is why the age carries the third: without it every
+    # dispatched worker is reported minutes into the work it was sent to do,
+    # and a signal firing on the healthy path is one an operator learns to
     # skip. The report still asks for a confirmation rather than asserting.
     echo "STALLED   #$n open at ${head:0:7}, no commit or reply in $((age / 3600))h"
     state=reported

package/claude/skills/claude-pr-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-pr-review
-description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while a critical or should-fix is open and `## Review closed` once nothing blocks the merge. Reads project docs and the roadmap for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes. That is `claude-review`.
+description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the roadmap for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes. That is `claude-review`.
 ---
 
 # Claude PR review
@@ -13,10 +13,10 @@ findings to the PR, so the vantage is independent and the output is durable.
 It posts at least twice over a pull request's life. A first pass opens the
 review against the whole change, and every later pass reads only the commits
 added since. The heading reports state rather than pass number: a pass carrying
-a critical or a should-fix takes `## Review`, and `## Review closed` covers
-every other pass, so the most recent comment's heading reports whether anything
-blocks the merge. Every pass is this skill, and which one it is gets detected
-from the thread rather than named by the caller.
+a finding at any severity takes `## Review`, and `## Review closed` covers a
+pass carrying none, so the most recent comment's heading reports whether any
+work is owed. Every pass is this skill, and which one it is gets detected from
+the thread rather than named by the caller.
 
 ## Guards
 
@@ -85,11 +85,11 @@ Review the diff and files for the same axes as `claude-review` (bugs, edge cases
 
 Apply the high-signal filter: flag only what will cause incorrect behavior, break a documented rule, or mislead a downstream feature. If uncertain, do not flag.
 
-A later pass applies the same axes to the delta, and adds one check the first pass cannot make: did each prior finding land, and did the fix regress anything it touched. Findings of its own are normal findings, stated at the same severity and counted the same way. That count is what Step 4 reads to pick the heading, so a pass raising a critical or a should-fix of its own is not a close-out.
+A later pass applies the same axes to the delta, and adds one check the first pass cannot make: did each prior finding land, and did the fix regress anything it touched. Findings of its own are normal findings, stated at the same severity and counted the same way. That count is what Step 4 reads to pick the heading, so a pass raising a finding of its own is not a close-out at any severity.
 
-A prior finding can also be settled by argument rather than by a fix. A reply naming the plan question that already declined it, or a constraint this session could not see, withdraws the finding or moves its grade. State that outcome in the body under the finding it changes, naming the fact that produced it, whether the argument arrived on the thread or through the channel that carried the dispatch. Dropping the finding from this body instead leaves a reader unable to tell a withdrawal from an oversight, and the reasoning goes with the session that heard it. A withdrawal removes the finding from the count, so a pass that withdrew every critical and should-fix is a close-out. Write the withdrawal and its cause into that body rather than taking the short close-out line Step 4 supplies, which reports prior findings addressed and would credit a fix nobody made.
+A prior finding can also be settled by argument rather than by a fix. A reply naming the plan question that already declined it, or a constraint this session could not see, withdraws the finding or moves its grade. State that outcome in the body under the finding it changes, naming the fact that produced it, whether the argument arrived on the thread or through the channel that carried the dispatch. Dropping the finding from this body instead leaves a reader unable to tell a withdrawal from an oversight, and the reasoning goes with the session that heard it. A withdrawal removes the finding from the count, so a pass that withdrew every finding it carried is a close-out. Write the withdrawal and its cause into that body rather than taking the short close-out line Step 4 supplies, which reports prior findings addressed and would credit a fix nobody made.
 
-Use severity: `critical` (blocks merge), `should-fix` (fix before merge), `minor` (visibility only).
+Use severity: `critical` (blocks merge), `should-fix` (fix before merge), `minor` (blocks nothing). The ladder ranks a finding and decides nothing about who acts on it, since every grade takes the open heading and owes a dispatch under the threshold Step 4 states.
 
 ## Step 4: post to the PR
 
@@ -144,15 +144,15 @@ Re-reviewed `<short-sha>`, N commits since the prior pass. X critical, Y should-
 🤖 Reviewed by Claude Code
 ```
 
-The heading reports whether anything blocks the merge and the summary line reports which pass this is. Post under `## Review` whenever the pass carries a critical or a should-fix, whether it is the first pass or the fourth. Post `## Review closed` on every other pass, a pass carrying only minors included, and list those minors under it as follow-ups. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `claude-address-review`, another `## Review` while a critical or should-fix is still open, and `## Review closed` when neither is.
+The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying a finding at any severity takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Sending that dispatch is `claude-orchestrate`'s step rather than this one, which posts and stops. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `claude-address-review`, another `## Review` while any finding is open, and `## Review closed` when none is.
 
-The heading and the dispatch answer two different questions, so a close-out does not mean the pass owes nobody. The heading says whether anything blocks the merge and the dispatch says whether any work is owed, and a pass carrying only minors closes the heading while still sending the session holding the branch. Keying the dispatch on the grade too was measured wrong: across 8 findings on one archived pass, 3 were posted as minor and 2 of those were defects a worker fixed rather than recorded, so a floor at should-fix loses real fixes to a grade that runs low.
+Keying either half on the grade was measured wrong: across 8 findings on one archived pass, 3 were posted as minor and 2 of those were defects a worker fixed rather than recorded, so a floor at should-fix loses real fixes to a grade that runs low. Splitting the two halves so the dispatch fired lower than the heading was the other candidate, and it left a thread reading closed while work was owed on it.
 
-The cost is that a clean thread no longer reads off the heading alone, since a close-out may carry minors. Take the merge decision from the heading and the counts from the summary line under it, which is where they already sit.
+The cost is that the merge decision no longer reads off the heading alone, since an open heading covers a minor as well as a critical. Take it from the counts on the summary line, which is where they already sit. No summary line reports the merge as unblocked under either heading, since a thread reading open cannot also report that nothing blocks it.
 
 A minor the dispatched worker declines is what needs a surface that survives the merge, rather than every minor, since one that gets fixed on the branch needs no durable record. Write a declined minor into the `## Findings` section of the task the branch closes, which is where the queue-refill sweep already routes a finding that changes another task. A declined finding left on the thread alone is lost the moment the pull request merges.
 
-Read the state off the most recent review comment rather than off the presence of a closed one. A close-out does not close the pull request, so a commit pushed after it gets its own pass, and that pass reopens the review under `## Review` when it raises a critical or a should-fix.
+Read the state off the most recent review comment rather than off the presence of a closed one. A close-out does not close the pull request, so a commit pushed after it gets its own pass, and that pass reopens the review under `## Review` when it raises a finding of any grade.
 
 Both of this skill's headings anchor as a section distinct from human threads. Do not invent one beyond those two and the `## Review response` a sibling owns, and do not append the PR number, which GitHub already renders above the comment.
 
@@ -172,14 +172,14 @@ Before posting, run the scan in `.claude/standards/publish.md` against the body,
 gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>-<short-sha>.md
 ```
 
-A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No blocking findings. Reviewed against project docs and roadmap.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`
+A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and roadmap.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`
 
-A pass carrying only minors takes the same heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. Keep whichever scope sentence the pass owes on the summary line:
+A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. Keep whichever scope sentence the pass owes on the summary line:
 
 ```markdown
-## Review closed
+## Review
 
-0 critical, 0 should-fix, Z minor. Nothing blocks the merge. Reviewed against project docs and roadmap.
+0 critical, 0 should-fix, Z minor. Reviewed against project docs and roadmap.
 
 **`path/to/file.ext`**
 

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

@@ -0,0 +1,46 @@
+---
+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
+- Route every edit inside a workspace file that already exists through a verb resolving the root in-process, since a heredoc reaches a whole-file create alone and the stream editors that would reach the rest are banned
+- 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
+- What the verbs do internally, which is the CLI domain's own contract rather than this skill's, and the records backup that carries the folder 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,115 @@
+---
+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: let the CLI 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.
+
+Every `aitk teach` verb resolves that root in-process, so no step below composes a path to a workspace file. Read the folder through the CLI rather than deriving its location:
+
+```bash
+aitk teach list --json
+```
+
+It reports every workspace with its path, its counts, and the ordinal a new one would take. A `no-teach` refusal means the project has opened none yet, which is the new-workspace path in Step 1 rather than a reason to stop. The open verb creates the folder.
+
+From a linked worktree the file-editing tools refuse every path under the main root and offer a worktree copy instead, which is a second file no later session reads. Never take that redirect. The route splits by what the write does to the file:
+
+- Creating a whole file that does not exist yet, which is a lesson, a reference page, and a learning record, goes out as one plain shell command carrying a heredoc
+- Changing a line inside a file that already exists goes through the verb that owns it, since the stream editors are banned and no other shell route reaches it
+
+## Step 1: open or resume
+
+A topic the listing already carries is a resume, and anything else is a new workspace.
+
+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 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 open the workspace, which derives the ordinal and writes all three required files:
+
+```bash
+aitk teach open <topic> --json \
+  --subject "<one line stating the subject>" \
+  --starting-point "<what the learner already knows>" \
+  --success "<an observable thing the learner will be able to do>" \
+  --out-of-scope "<what this workspace does not cover>"
+```
+
+Repeat `--success` and `--out-of-scope` per line. The verb refuses a topic another workspace already covers, which is the guard against opening a second one on the same subject.
+
+## Step 2: research before teaching
+
+Read the subject from sources rather than from recall. Record what was read and what was only found through the verb that owns the file:
+
+```bash
+aitk teach resource <topic> --json \
+  --read "<title, naming which claims rest on it>=<url>" \
+  --lead "<title>=<url>"
+```
+
+Each flag repeats, and the pair splits on the first `=` so a URL carrying one survives. A URL already listed is refused rather than repeated.
+
+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` through the verb, which places the entries alphabetically in the shape the standard fixes:
+
+```bash
+aitk teach glossary <topic> --json \
+  --term "<term>=<definition, written without using the term>" \
+  --first-seen <the lesson or reference page this batch comes from>
+```
+
+`--term` repeats and one call writes the file once, which is what keeps a batch of terms from racing on it. A term already defined is refused, since a definition the subject has moved under is a revision of the entry rather than a second one.
+
+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/commands.md

@@ -32,6 +32,10 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk tasks validate`      | Report board rows whose plan, task file, group, file set, or blocker does not hold (`--json`)                                             |
 | `aitk intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                     |
 | `aitk intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                            |
+| `aitk teach list`          | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                        |
+| `aitk teach open`          | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                           |
+| `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                     |
+| `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                       |
 | `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                              |
 | `aitk records push`        | Commit the eight backed record folders and push them to a private records remote (`--json`)                                               |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                   |
@@ -59,6 +63,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `slides`    | `render`, `list`                                                                            |
 | `tasks`     | `archive`, `validate`                                                                       |
 | `intake`    | `list`, `answer`                                                                            |
+| `teach`     | `list`, `open`, `resource`, `glossary`                                                      |
 | `comments`  | `scan`                                                                                      |
 | `context`   | `audit`                                                                                     |
 | `markdown`  | `audit`                                                                                     |

package/docs/agents/index.md

@@ -26,3 +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 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

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.