@erclx/aitk 1.0.1 → 1.2.0

package/governance/rules/claude/555-tasks.md

@@ -16,5 +16,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/tasks.md` for filenames, frontmatter, what belongs, and the task file format. It is the single source.
+- Follow the tasks standard for filenames, frontmatter, what belongs, and the task file format. It is the single source. Read it with `aitk standards tasks`.
 - Never hand-edit `.claude/tasks/index.md`. A hook regenerates it from sibling frontmatter.

package/governance/rules/claude/556-groundwork.md

@@ -13,4 +13,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/groundwork.md` for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source.
+- Follow the groundwork standard for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source. Read it with `aitk standards groundwork`.

package/governance/rules/claude/557-intake.md

@@ -13,4 +13,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/intake.md` for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source.
+- Follow the intake standard for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source. Read it with `aitk standards intake`.

package/governance/rules/claude/558-plan.md

@@ -20,4 +20,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/plan.md` for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source.
+- Follow the plan standard for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source. Read it with `aitk standards plan`.

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

@@ -17,4 +17,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source.
+- Follow the memory standard for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source. Read it with `aitk standards memory`.

package/governance/rules/claude/560-diagrams.md

@@ -9,7 +9,7 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source.
+- Follow the diagrams standard for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source. Read it with `aitk standards diagrams`.
 - A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
 
 ## Scope

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

@@ -16,5 +16,6 @@ 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.
+- Follow the teach standard for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source. Read it with `aitk standards teach`.
+- 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/governance/rules/claude/562-session.md

@@ -16,4 +16,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/session.md` for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source.
+- Follow the session standard for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source. Read it with `aitk standards session`.

package/governance/rules/claude/570-skill.md

@@ -20,4 +20,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, invocation rules, and the shape a `REQUIREMENT.md` states. It is the single source.
+- Follow the skill standard for skill structure, frontmatter fields, invocation rules, and the shape a `REQUIREMENT.md` states. It is the single source. Read it with `aitk standards skill`.

package/governance/rules/claude/580-readme.md

@@ -16,4 +16,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/readme.md` for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source.
+- Follow the readme standard for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source. Read it with `aitk standards readme`.

package/governance/rules/claude/590-rule-authoring.md

@@ -19,5 +19,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/rule.md` for rule frontmatter, body shape, and voice. It is the single source.
+- Follow the rule-authoring standard for rule frontmatter, body shape, and voice. It is the single source. Read it with `aitk standards rule`.
 - Read it before writing or editing a rule. Do not work the shape from memory.

package/governance/rules/claude/591-standard-authoring.md

@@ -17,5 +17,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/standard.md` for a standard's frontmatter, shape, scope, and success criterion. It is the single source.
+- Follow the standard-authoring standard for a standard's frontmatter, shape, scope, and success criterion. It is the single source. Read it with `aitk standards standard`.
 - Read it before writing or editing a standard. Do not work the shape from memory.

package/package.json

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

package/src/markdown/structure.ts

@@ -536,10 +536,45 @@ function measureParagraph(block: readonly BodyLine[]): CadenceFinding {
  * absence of something, so no addition to that set catches a paragraph whose
  * sentences are all one length. The measure stops at what is countable. A
  * sentence's grammatical shape and whether it carries a finite verb are the two
- * rules `write-human` states that this does not implement, because identifying
- * either needs a parse rather than a match, and an imperative or a heading
- * fragment would read as a defect. Reporting them wrong is worse than not
- * reporting them, since they name the exact failure this exists to measure.
+ * rules `write-human` states that this does not implement. Reporting them wrong
+ * is worse than not reporting them, since they name the exact failure this
+ * exists to measure.
+ *
+ * That was a prediction and it has now been measured, against two parsers
+ * rather than against the idea of one. Both ran over 11,389 paragraph sentences
+ * across 503 markdown files at `c7e92612` on 2026-08-20, and they disagree by
+ * a factor of four on a number one of them has to be wrong about.
+ *
+ * `compromise` reported 2 percent. It tags a fronted past participle as a
+ * finite past-tense verb, so all twelve of those sentences in
+ * `.claude/ARCHITECTURE.md` read as carrying one, eleven opening `Measured at`
+ * and one `Overturned by`, which is the exact shape the measure exists to
+ * catch. It is not even consistent with itself there: `Measured at` tags a verb
+ * and `Measured against` tags an adjective.
+ *
+ * `wink-pos-tagger` reported 9 percent and fixes that class, tagging the
+ * participle `VBN`. Roughly three quarters of what it flags is still wrong:
+ * hand-classifying every 21st of the 1,071 flagged sentences put 12 of 51
+ * genuinely verbless. Two classes split the other 39 almost evenly and neither
+ * is a tuning problem. Nineteen are imperatives, which this instructional
+ * corpus is full of and whose verb tags as a proper noun as often as a verb.
+ * Twenty are ordinary declaratives whose predicate is noun-ambiguous and tags
+ * as a noun outright, so `Each maps to a skill.` and `Nothing checks either
+ * one.` both report verbless. This corpus is built from exactly those words:
+ * reports, answers, checks, maps, holds, names, carries, records, measures.
+ *
+ * Separating them needs to know which token is the predicate, which is syntax
+ * rather than a tag. Neither tagger carries one and nothing was found worth
+ * taking for a number nothing gates on, so the rule the deferral set is met and
+ * still returns no: a parse was tried, twice, and neither produced a number
+ * worth printing beside two that hold.
+ *
+ * Where a shape sits is a different question and is already answered. A heading
+ * fragment, a list item, and a table cell are all legitimately verbless and
+ * none of them reaches this measure, because `paragraphBlocks` ends a paragraph
+ * on each. That exclusion is structural and needs no grammar. The imperative is
+ * the one that sits in paragraph prose, and it is what neither parser could
+ * separate out.
  *
  * A paragraph under the floor is skipped rather than scored. A two-sentence
  * configuration note has no spread worth reading, and the opener rule is

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

@@ -207,7 +207,9 @@ Why this task exists and what it depends on.
 
 Every task names where it came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title. Include each only when the file, folder, or issue it names exists.
 
-A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track or an open issue that no task points at is work already decided and on its way to being forgotten. An intake folder is exempt from that direction, since it dispositions many items at once and most of them close without ever becoming a task.
+A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track, an intake folder, or an open issue that no task points at is work already decided and on its way to being forgotten.
+
+An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive beside the board is what separates it from one already promoted and shipped, and a check reading the board alone calls every finished folder abandoned.
 
 `Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.claude/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
 

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