@erclx/aitk 1.0.0 → 1.1.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-memory-review/REQUIREMENT.md

@@ -9,7 +9,7 @@ description: What memory review is for, the gaps it closes, and why every action
 
 Without this skill, the memory folder grows and never drains. Entries pile up restating rules a durable surface already carries, nothing decides which memory has earned a place in one, and a rule that does get promoted arrives verbatim in a file whose voice it does not match. The folder then reads as a second source of truth that no surface points at.
 
-A pen the caller cannot face is the same gap wearing a different shape. Once routing at capture takes the domain facts, what reaches this skill is feedback about how to work, which is a working set rather than a backlog, and the proposal is a size a person actually reads. An entry leaving the pen is archived rather than deleted, because a folder git does not hold gives a wrong bulk call no undo.
+A pen the caller cannot face is the same gap wearing a different shape. Routing at capture takes the domain facts and whatever the ownership test leaves stays, in whatever mix of types that is, so the folder still reaches a size nobody reads in one sitting. A ship-time run is scoped to the entries that session captured for exactly that reason, and the full sweep is what an operator asks for when the cross-session duplicates are the point. An entry leaving the pen is archived rather than deleted, because a folder git does not hold gives a wrong bulk call no undo.
 
 ## Must
 

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

@@ -25,6 +25,6 @@ The requirement is a resume request to the orchestrator skill with that skill lo
 
 Step 1 exists because both other callers of capture are ship-chain skills and this session never ships. Without a call here, the session that receives every operator correction is the one session that records none. A compaction arriving with no warning takes the capture with it, and firing it once per batch of merges leaves the same window open across a long planning stretch, since a sweep runs only on a merge. The refill sweep reports the debt between handoffs so the operator knows one is owed.
 
-Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and the orchestrator's boundaries forbid writing one from this session. That split is correct rather than a limitation, since a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work, which is the class the memory folder keeps.
+Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and the orchestrator's boundaries forbid writing one from this session. That split is correct rather than a limitation, since a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work.
 
 The core's drift step answers where the working directory carries `claude/skills/` with history behind it, which is the toolkit repository itself, and refuses by naming the absent tree anywhere else. A project consuming the plugin from a marketplace cache is that second case, so read the refusal as the boundary rather than as a fault.

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

@@ -9,7 +9,7 @@ argument-hint: <subject to learn, or the topic of a workspace to resume or promo
 
 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 glossary answers to `.claude/standards/glossary.md`, or `${CLAUDE_SKILL_DIR}/../../standards/glossary.md` when the project does not have it. The pedagogy sits in `${CLAUDE_SKILL_DIR}/references/pedagogy.md`, the lesson craft in `${CLAUDE_SKILL_DIR}/references/lesson-craft.md`, and the promotion routing in `${CLAUDE_SKILL_DIR}/references/promotion.md`.
+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 glossary answers to `${CLAUDE_SKILL_DIR}/references/glossary.md`, which travels with this skill rather than installing, because a promoted glossary keeps its shape at whatever path it lands on and no project folder covers all of them. The pedagogy sits in `${CLAUDE_SKILL_DIR}/references/pedagogy.md`, the lesson craft in `${CLAUDE_SKILL_DIR}/references/lesson-craft.md`, and the promotion routing in `${CLAUDE_SKILL_DIR}/references/promotion.md`.
 
 ## Guards
 

package/{standards → claude/skills/claude-teach/references}/glossary.md

@@ -1,6 +1,7 @@
 ---
 title: Glossary reference
 description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
+consumers: claude-teach
 ---
 
 # Glossary reference

package/docs/agents/records.md

@@ -23,7 +23,7 @@ aitk records validate intake --json
 
 It reads and never writes, and the reason splits by kind. A session record is per-machine scratch with no history behind it, so a repair that guessed wrong could not be undone. A standard installs into every target and is cited by bare filename, so a rename the verb performed would reach further than the file it moved, which is why a finding naming one says so.
 
-`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.
+`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. Location decides that rather than subject, since a member there reaches its readers as a copy in each consuming skill and never as an installed file, which is the same reason install and sync skip the folder. What it costs is that a standard moved into the fan-out leaves the validator with nothing reporting the move.
 
 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.
 

package/docs/agents/teach.md

@@ -5,7 +5,7 @@ description: Listing learning workspaces and the ordinal a new one takes, openin
 
 # Teach
 
-Learning workspaces sit under `.claude/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats, apart from the glossary, whose shape `standards/glossary.md` fixes so it travels with the file wherever a promotion lands it. 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.
+Learning workspaces sit under `.claude/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats, apart from the glossary, whose shape `standards/bundled/glossary.md` fixes and fans out into the `claude-teach` skill, so it travels with the file wherever a promotion lands it. 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.
 

package/governance/rules/claude/559-memory.md

@@ -8,7 +8,7 @@ paths:
 
 ## Routing
 
-- Write no memory entry for a fact a per-domain context entry already owns. Memory keeps the residue, which in practice is feedback about how to work.
+- Write no memory entry for a fact a per-domain context entry already owns.
 
 ## The pen
 

package/governance/rules/claude/561-teach.md

@@ -17,4 +17,5 @@ paths:
 ## Authority
 
 - Follow `.claude/standards/teach.md` for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source.
-- Follow `.claude/standards/glossary.md` for the glossary every workspace carries at its root.
+- Read `references/glossary.md` inside the `claude-teach` skill for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it rather than invoking the skill, which resumes a workspace and runs lessons.
+- Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/package.json

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

package/standards/bundled/glossary.md

@@ -0,0 +1,76 @@
+---
+title: Glossary reference
+description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
+consumers: claude-teach
+---
+
+# Glossary reference
+
+Applies to a glossary, the file holding one entry per term a body of material defines. It changes whenever the material names a concept a reader cannot look up yet, and it is revised in place rather than appended to.
+
+## Scope
+
+Governs a glossary at `.claude/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
+
+Does not govern:
+
+- The folder a learning workspace lays out around its glossary, and the other files in it: `teach.md`
+- Which surface a glossary moves to once it leaves the material that produced it, which belongs to the surface driving that move
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+
+## What a working glossary looks like
+
+A glossary works when a reader who meets a term in the material settles it here without opening the page that introduced it:
+
+- Which word does this material use for the concept, and which words does it deliberately not use?
+- What does the term mean, stated without leaning on the term itself?
+- Where does the term appear, so a reader can see it used rather than only defined?
+- Does every entry carry a term the material actually uses?
+
+A glossary failing these is non-conforming even when it satisfies every shape rule below.
+
+## Frontmatter
+
+- `title` (required): names the material the terms come from, in sentence case
+- `description` (required): one line naming what a reader gets from the entries
+
+## Entries
+
+- Write one entry per term, as a single bullet.
+- Lead the bullet with the term as a bolded span, then the definition in one or two sentences.
+- Define the term without using it. A definition that spends the term explains nothing to the reader who arrived not knowing it.
+- Name where the term first appears, so a reader can reach one use of it in context.
+- Keep an entry to the meaning. Worked detail belongs on the page that teaches the term.
+- Sort entries alphabetically, so a reader who knows only the word finds it without reading the file.
+
+## Which terms it carries
+
+- Add a term once the material has used it, never ahead of that. A glossary front-loaded with terms nothing has introduced is a syllabus rather than a reference.
+- Pick one word per concept and use that word everywhere. A glossary carrying two words for one thing hands the reader a choice it exists to remove.
+- List each rejected synonym as an alias to avoid inside the entry that won, so a reader arriving with the wrong word lands on the right one.
+- Use the glossary's own terms inside other definitions. A definition reaching for a synonym of a term defined two entries down teaches the reader a word the material does not use.
+- Revise an entry the material has moved under rather than adding a second one narrating the change.
+
+## Grouping
+
+- Keep a short glossary as one alphabetical list under the title. Grouping a handful of entries costs a heading per category and saves no lookup.
+- Group a glossary long enough that one list stops helping under `##` headings by category, sorted alphabetically within each. Roughly two screens of entries is the signal.
+- Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
+- State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
+
+## Template
+
+```markdown
+---
+title: <Material the terms come from>
+description: <one line naming what a reader gets from these entries>
+---
+
+# <Material the terms come from>
+
+<One line on which material these terms come from and when the file changes.>
+
+- **<Term>**: <the meaning in one or two sentences, written without using the term>. Avoid <rejected synonym>. First appears in `<page or lesson>`.
+- **<Term>**: <the meaning in one or two sentences, written without using the term>. First appears in `<page or lesson>`.
+```

package/standards/index.md

@@ -11,7 +11,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
-- [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording

package/standards/memory.md

@@ -46,7 +46,7 @@ Four types, and the type decides both the filename prefix and the body shape.
 
 Hold a feedback entry to the higher bar. A first-occurrence slip is noise, and a folder that records every one of them buries the rules that were paid for.
 
-Write no entry for a fact another surface already owns. A fact about a domain belongs in that domain's entry, where sessions working the domain already read it, and the same fact in memory sits in a folder nothing opens. Memory keeps the residue, which in practice is feedback about how to work.
+Write no entry for a fact another surface already owns. A fact about a domain belongs in that domain's entry, where sessions working the domain already read it, and the same fact in memory sits in a folder nothing opens. Memory keeps the residue, which is whatever the ownership test leaves rather than any one type.
 
 ## Filename
 

package/standards/teach.md

@@ -15,7 +15,7 @@ Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout,
 
 Does not govern:
 
-- The frontmatter, entry shape, and ordering of the glossary the workspace holds: `glossary.md`
+- The frontmatter, entry shape, and ordering of the glossary the workspace holds: the `claude-teach` skill, which carries that reference
 - What a lesson teaches, how it sequences difficulty, and what makes one worth returning to, which belong to the surface driving the workspace
 - Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
 - One question measured in depth before anyone can plan against it: `groundwork.md`
@@ -97,9 +97,9 @@ Record the wrong answer rather than the fact of an error. A wrong answer names t
 
 ## GLOSSARY.md
 
-Required in every workspace, holding one entry per term the subject defines. `glossary.md` fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root.
+Required in every workspace, holding one entry per term the subject defines. The glossary reference the `claude-teach` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
 
-Name the lesson or reference page a term first appears in as that standard requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.
+Name the lesson or reference page a term first appears in as that reference requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.
 
 ## RESOURCES.md