@erclx/aitk 0.100.0 → 0.102.0

package/docs/agents/teach.md

@@ -0,0 +1,119 @@
+---
+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
+---
+
+# Teach
+
+Learning workspaces sit under `.claude/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats. Every verb here resolves that folder against the main worktree root rather than against the working directory, so a session standing in a linked worktree reaches the one workspace the learner has rather than opening a second.
+
+That root resolution is also why the writing verbs exist at all. The file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead, and a caller naming only the destination reports a success that did not happen. A whole-file create still goes out as a shell heredoc. Changing a line inside a file that already exists has no shell route, because the stream editors are banned, so `resource` and `glossary` are the route for the two files a running workspace edits.
+
+## List
+
+`aitk teach list` reports the workspaces under `.claude/teach/`, or what one workspace holds. It reads and never writes.
+
+```bash
+aitk teach list
+aitk teach list regular-expressions --json
+```
+
+| Option          | Behavior                                    |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Teach root, defaulting to the main worktree |
+
+With no topic it reports one line per workspace, carrying the lesson, learning-record, reference-page, and glossary-term counts, plus `next`, the ordinal an open would take. With one it reports the filenames behind each count and the glossary entries themselves.
+
+A folder not named `NN-<topic>` is still listed rather than dropped, since dropping it hides the one folder that needs a fix. Its ordinal reads as absent, it sorts last, and it moves no ordinal, so a malformed name cannot push a new workspace into a number a reader already cites.
+
+The listing also names the required files a workspace does not carry, which is `MISSION.md`, `RESOURCES.md`, and `GLOSSARY.md`. That is a report rather than a refusal, because a workspace missing one is still a workspace a session can resume.
+
+## Open
+
+`aitk teach open` creates a workspace at the next ordinal and writes all three required files.
+
+```bash
+aitk teach open regular-expressions \
+  --subject "Reading and writing regular expressions" \
+  --starting-point "Comfortable with the shell, has never written a group" \
+  --success "Write a pattern matching a date" \
+  --success "Explain what a backreference does"
+```
+
+| Option                    | Behavior                                                    |
+| ------------------------- | ----------------------------------------------------------- |
+| `--subject <line>`        | One line stating what the workspace covers, required        |
+| `--starting-point <text>` | What the learner already knows, required                    |
+| `--success <line>`        | Observable thing the learner will be able to do, repeatable |
+| `--out-of-scope <line>`   | What the workspace does not cover, repeatable               |
+| `--title <text>`          | Title, defaulting to the topic in sentence case             |
+| `--date <YYYY-MM-DD>`     | Opening date, defaulting to today                           |
+| `--json`                  | Emit a machine-readable record on stdout                    |
+| `--root <path>`           | Teach root, defaulting to the main worktree                 |
+
+The ordinal comes from the highest already present, incremented, so the caller derives no name and composes no path. A topic another workspace already covers is refused rather than opened beside it, since two workspaces on one subject fork the learning records the folder exists to keep whole.
+
+`--starting-point` is required rather than defaulted because difficulty with no floor under it teaches nobody, and a mission written without one cannot say what the lessons sit above. At least one `--success` line is required for the same reason in the other direction: a mission nothing can test is a mission nothing can call finished.
+
+## Resource
+
+`aitk teach resource` records sources in a workspace `RESOURCES.md`, keeping what was read apart from what was only found.
+
+```bash
+aitk teach resource regular-expressions \
+  --read "MDN regular expressions=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions" \
+  --lead "RE2 syntax=https://github.com/google/re2/wiki/Syntax"
+```
+
+| Option               | Behavior                                           |
+| -------------------- | -------------------------------------------------- |
+| `--read <title=url>` | Source that stands behind the material, repeatable |
+| `--lead <title=url>` | Source found and not opened, repeatable            |
+| `--json`             | Emit a machine-readable record on stdout           |
+| `--root <path>`      | Teach root, defaulting to the main worktree        |
+
+The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from.
+
+A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer.
+
+A URL a file displays inside a fence does not count as listed, which is how a workspace quoting the entry format in its own prose is read as the sample it is.
+
+## Glossary
+
+`aitk teach glossary` adds terms to a workspace `GLOSSARY.md`, alphabetically.
+
+```bash
+aitk teach glossary regular-expressions \
+  --term "capture group=A parenthesised part of a pattern whose match is kept" \
+  --first-seen 0002-groups.html
+```
+
+| Option                     | Behavior                                                  |
+| -------------------------- | --------------------------------------------------------- |
+| `--term <term=definition>` | Term the subject defines, repeatable                      |
+| `--first-seen <file>`      | Lesson or reference page the batch first defines these in |
+| `--json`                   | Emit a machine-readable record on stdout                  |
+| `--root <path>`            | Teach root, defaulting to the main worktree               |
+
+One call writes one file, which keeps a batch of terms from racing on the glossary every one of them shares. `--first-seen` names one page for the whole batch rather than one per term, because a batch comes from one lesson.
+
+A term already defined is refused rather than replaced. A definition the subject has moved under is a revision of the entry that exists, and nothing on the command line tells that apart from a second definition arriving by mistake.
+
+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.
+
+## Refusal reasons
+
+| Reason         | Raised when                                                     |
+| -------------- | --------------------------------------------------------------- |
+| `no-teach`     | The root carries no `.claude/teach/` folder                     |
+| `no-workspace` | No workspace matches the topic, with the folder names as detail |
+| `ambiguous`    | Two workspaces claim one topic, with both names as detail       |
+| `exists`       | A workspace already covers the topic an open names              |
+| `no-file`      | The workspace carries no file the verb writes into              |
+| `no-section`   | `RESOURCES.md` carries no heading the entries belong under      |
+| `listed`       | A URL is already listed under either heading                    |
+| `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.

package/docs/ai-workflow.md

@@ -73,7 +73,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 - Ship each worktree separately with `aitk:git-ship`
 - For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
 
-To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `aitk:claude-orchestrate`. It owns the roadmap, handing a needed draft or resequence to a worker that runs `aitk:claude-roadmap` in its branch, plans each feature, refills the ready queue so a free worker never waits, and reviews each worker's PR with `aitk:claude-pr-review`, then tells the session holding that branch to run `aitk:claude-address-review` whenever the pass posted a finding at any severity, read off the counts on the summary line rather than off the heading above them. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
+To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `aitk:claude-orchestrate`. It owns the roadmap, handing a needed draft or resequence to a worker that runs `aitk:claude-roadmap` in its branch, plans each feature, refills the ready queue so a free worker never waits, and reviews each worker's PR with `aitk:claude-pr-review`, then tells the session holding that branch to run `aitk:claude-address-review` whenever the pass posted a finding at any severity, which is the same threshold `aitk:claude-pr-review` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
 
 Roadmap ownership holds while a scope exists to sequence. Once the MVP list in `.claude/REQUIREMENTS.md` has shipped, later work arrives as discrete items and the orchestrator reads `.claude/tasks/priority.md` for execution order instead.
 

package/docs/operating-model.md

@@ -40,8 +40,8 @@ One feature travels this path end to end.
 2. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
 3. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker builds, self-checks, opens a PR, and stops at the PR boundary.
 4. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
-5. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target from a session listing taken at that moment and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made.
-6. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds a critical or a should-fix and under `## Review closed` otherwise, so a reader learns the merge decision from the heading and the counts from the line under it. Repeat from step 5 until a pass closes the review.
+5. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target from a session listing taken at that moment and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
+6. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. Repeat from step 5 until a pass closes the review.
 7. The human reads the result and merges. The orchestrator tells any trailing worker whose branch shares a seam with the merged one to run `claude-address-review`, which rebases whether or not the review left anything open.
 
 There is no loop construct here. Each worker is a single build that halts at the
@@ -103,12 +103,13 @@ re-read costs a full pass rather than a delta, since the prior reviewed commit n
 longer reaches the head, and `claude-pr-review` detects that itself.
 
 The heading carries the state rather than the pass number. A pass carrying a
-critical or a should-fix takes `## Review` and every other pass takes
-`## Review closed`, so a thread can be scanned for what still blocks a merge
-without opening a comment. The heading and the dispatch answer two questions
-rather than one: a minors-only pass closes the heading and still sends a worker,
-so the dispatch reads the counts on the summary line rather than the heading
-above them. A minor the worker declines goes to the findings of the task the
+finding at any severity takes `## Review` and a pass carrying nothing takes
+`## Review closed`, so a thread can be scanned for what still owes work without
+opening a comment. One threshold governs the heading and the dispatch alike, and
+`claude-pr-review` is where it is stated, so every other surface cites that skill
+rather than restating the grades. The merge decision comes off the counts on the
+summary line, since an open heading now covers a minor as well as a critical.
+A minor the worker declines goes to the findings of the task the
 branch closes, since a thread does not survive the merge. The feedback
 becomes a durable artifact both sessions read, survives a session ending, and
 anchors to the change. That removes the copy-paste that otherwise routes review

package/docs/target-projects.md

@@ -89,7 +89,7 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 `governance`, `standards`, and `wiki` are skippable:
 
 - `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/prose.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
-- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing for a reader following the path. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root, and so is the CLI, which searches the corpus inside its own package behind both project roots. `aitk markdown audit` and `aitk standards <name>` therefore answer in a project that skipped the install, and what the skip costs is the editable copy rather than the enforcement.
+- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing for a reader following the path. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root. `aitk standards <name>` searches the corpus inside the CLI's own package behind both project roots, so it prints a standard in a project that skipped the install, and `aitk markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data. What the skip costs is the editable copy rather than the enforcement.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 
 That standards fallback carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.

package/package.json

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

package/scripts/core/verify.sh

@@ -363,6 +363,9 @@ main() {
   1)
     log_warn "Skipped, the markdown audit refused and measured nothing"
     ;;
+  3)
+    log_error "The markdown audit shipped an empty ban set, so the corpus was walked and nothing was looked for. Check src/markdown/bans.ts."
+    ;;
   2)
     # `|| true` because the re-run exits non-zero by construction, and `set -e`
     # would take the script down before log_error names the remedy.

package/src/cli.ts

@@ -21,6 +21,7 @@ import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
 import { register as intake } from '@/commands/intake'
+import { register as teach } from '@/commands/teach'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
@@ -56,6 +57,7 @@ function showHelp(): void {
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
     `${GREY}│${NC}    intake [cmd]       ${GREY}# Intake folders under .claude/intake/ (list, answer)${NC}`,
+    `${GREY}│${NC}    teach [cmd]        ${GREY}# Learning workspaces under .claude/teach/ (list, open, resource, glossary)${NC}`,
     `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
@@ -92,6 +94,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
     `${GREY}│${NC}    aitk intake list toolkit-overview --unread --json`,
+    `${GREY}│${NC}    aitk teach list --json`,
     `${GREY}│${NC}    aitk comments scan src --json`,
     `${GREY}│${NC}    aitk context audit --json`,
     `${GREY}│${NC}    aitk markdown audit .claude/rules --json`,
@@ -150,6 +153,7 @@ feedback(program)
 transcripts(program)
 tasks(program)
 intake(program)
+teach(program)
 comments(program)
 context(program)
 markdown(program)

package/src/commands/markdown.ts

@@ -1,14 +1,19 @@
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { type BanReport, banReport, loadStandards } from '@/markdown/bans'
+import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
 import { resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
-import { type BanFinding, bodyLines, scanBans } from '@/markdown/scan'
 import {
+  type BanFinding,
+  type BanSets,
+  bodyLines,
+  scanBans,
+} from '@/markdown/scan'
+import {
+  CHECKPOINTS,
   type Checkpoints,
   measureStructure,
-  parseCheckpoints,
   type StructureReport,
 } from '@/markdown/structure'
 import {
@@ -21,8 +26,19 @@ import {
   plural,
 } from '@/ui'
 
+const EXIT_REFUSED = 1
 const EXIT_GATE = 2
 
+/**
+ * A set shipped empty, so the run measured a corpus against nothing.
+ *
+ * Distinct from `EXIT_REFUSED` because the two want different responses. A
+ * refusal means no corpus was built and a push stage is right to skip, while an
+ * empty set means the corpus was walked and nothing was looked for, which is a
+ * defect in the build and has to fail.
+ */
+const EXIT_UNUSABLE = 3
+
 interface AuditCommandOptions {
   readonly json?: boolean
 }
@@ -58,6 +74,7 @@ export function register(program: Command): void {
         '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
         '  2  a banned character, word, or spelling is present',
+        '  3  a shipped ban set is empty, so the run measured nothing',
         '',
         'A ban hit is a fact and gates unconditionally. Bullet, paragraph, and',
         'depth weight are judgments a reader settles, so all three report and',
@@ -68,12 +85,11 @@ export function register(program: Command): void {
         'where the token is genuinely an identifier under discussion, which is',
         'what markdown.md reserves the span for.',
         '',
-        'Bans and checkpoints are read from markdown.md and prose.md, resolved',
-        'under .claude/standards/, then standards/, then the corpus inside the',
-        'aitk package, so a project that installed neither is still measured.',
-        'The report names the copy it read. No folder has to resolve and no',
-        'index.md has to exist, so .claude/rules/, governance/, and snippets/',
-        'are in reach.',
+        'Bans and checkpoints ship with the aitk package rather than being read',
+        'out of a standards file, so a project that installed no standards is',
+        'measured the same as one that did. markdown.md and prose.md still state',
+        'every rule for a reader. No folder has to resolve and no index.md has',
+        'to exist, so .claude/rules/, governance/, and snippets/ are in reach.',
         '',
         'Examples:',
         '  aitk markdown audit',
@@ -110,9 +126,9 @@ async function runAudit(
     )
   }
 
-  const standards = await loadStandards(root)
-  const bans = banReport(standards)
-  const checkpoints = parseCheckpoints(standards.markdown?.text ?? '')
+  const bans = BAN_SETS
+  const empty = emptyBanSets(bans)
+  const checkpoints = CHECKPOINTS
 
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
@@ -127,7 +143,7 @@ async function runAudit(
 
   intro('aitk markdown audit')
   reportScope(scope.files, scope.unmatched)
-  reportBans(reports, bans)
+  reportBans(reports, bans, empty)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportDepth(reports, checkpoints)
@@ -143,8 +159,7 @@ async function runAudit(
           characters: bans.characters,
           words: bans.words,
           spellings: bans.spellings,
-          sources: bans.sources,
-          missingStandards: bans.missing,
+          emptySets: empty,
         },
         checkpoints: {
           run: checkpoints.run,
@@ -153,7 +168,6 @@ async function runAudit(
           paragraph: checkpoints.paragraph,
           sentences: checkpoints.sentences,
           renderWidth: checkpoints.renderWidth,
-          fellBack: checkpoints.fellBack,
         },
         entries: reports.map((report) => ({
           path: report.rel,
@@ -167,6 +181,10 @@ async function runAudit(
     )
   }
 
+  // An empty set finds nothing and would exit clean, which reports a corpus
+  // nobody checked as a corpus carrying no violation.
+  if (empty.length > 0) return EXIT_UNUSABLE
+
   const gating = isGating({
     bans: reports.flatMap((report) => report.bans),
     structure: reports.map((report) => report.structure),
@@ -180,7 +198,7 @@ function refuse(message: string): number {
   logStep('Refused')
   logWarn(message)
   outro()
-  return 1
+  return EXIT_REFUSED
 }
 
 function reportScope(
@@ -203,18 +221,22 @@ function reportScope(
  * the sentence and every voice rule is a judgment, so a report listing hits
  * without naming those would read as a verdict on the whole standard.
  */
-function reportBans(reports: readonly FileReport[], bans: BanReport): void {
+function reportBans(
+  reports: readonly FileReport[],
+  bans: BanSets,
+  empty: readonly string[],
+): void {
   logStep('Bans')
 
-  if (bans.missing.length > 0) {
+  if (empty.length > 0) {
     logWarn(
-      `Not measured. Found no copy of: ${bans.missing.join(', ')}. Looked under .claude/standards/, then standards/, then the aitk package.`,
+      `Not measured. The shipped set is empty for: ${empty.join(', ')}. The sets ship with the aitk package, so an empty one is a defect in the build rather than a missing install.`,
     )
-    if (bans.sources.length === 0) return
+    return
   }
 
   logInfo(
-    `${plural(bans.characters.length, 'character')}, ${plural(bans.words.length, 'word')}, and ${plural(bans.spellings.length, 'spelling')} read from ${bans.sources.join(' and ')}`,
+    `${plural(bans.characters.length, 'character')}, ${plural(bans.words.length, 'word')}, and ${plural(bans.spellings.length, 'spelling')} shipped with the aitk package`,
   )
   logInfo(
     'Frontmatter, fenced blocks, code spans, and link destinations are excluded.',
@@ -379,12 +401,6 @@ function reportDepth(
     'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
   )
 
-  if (checkpoints.fellBack.length > 0) {
-    logWarn(
-      `Read no number from the standard for: ${checkpoints.fellBack.join(', ')}. Measured against the shipped default instead.`,
-    )
-  }
-
   const over = reports
     .filter((report) => report.structure.longestRun > checkpoints.run)
     .sort((a, b) => b.structure.longestRun - a.structure.longestRun)

package/src/commands/tasks.ts

@@ -104,7 +104,7 @@ export function register(program: Command): void {
         '',
         'Checks:',
         '  every Run now row points at a plan file that resolves',
-        '  every row maps to a task file and every task file to a row',
+        '  every task file carries a board row or a backlog line, never both',
         '  no task carries more than one row',
         '  no two Run now rows touch the same file',
         '',
@@ -450,12 +450,14 @@ function reportValidation(
     intro('aitk tasks validate')
     logStep('Board')
     logInfo(
-      `${outcome.rows} row(s) across the readiness groups, ${outcome.tasks} task file(s)`,
+      `${outcome.rows} row(s) across the readiness groups, ${outcome.backlog} backlog line(s), ${outcome.tasks} task file(s)`,
     )
 
     logStep(outcome.findings.length === 0 ? 'Clean' : 'Findings')
     if (outcome.findings.length === 0) {
-      logInfo('every row resolves, maps one to one, and touches its own files')
+      logInfo(
+        'every row resolves, every task sits on one surface, and each touches its own files',
+      )
     } else {
       for (const finding of outcome.findings) logWarn(describe(finding))
     }
@@ -481,6 +483,7 @@ function reportValidation(
         ok: true,
         root,
         rows: outcome.rows,
+        backlog: outcome.backlog,
         tasks: outcome.tasks,
         findings: outcome.findings,
         untested: outcome.untested,