@erclx/aitk 0.105.0 → 0.107.0

package/docs/agents/markdown-audit.md

@@ -5,7 +5,7 @@ description: Running the audit over any markdown path, where its bans and checkp
 
 # Markdown audit
 
-`aitk markdown audit [path...]` reports any markdown file against the two attribute standards, `markdown.md` and `prose.md`. An attribute standard governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/`, `governance/`, and `snippets/` in reach. Folder-shaped findings stay in `aitk context audit`, described in `context-audit.md`.
+`aitk markdown audit [path...]` reports any markdown file against the attribute standard `markdown.md`. An attribute standard governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/`, `governance/`, and `snippets/` in reach. Folder-shaped findings stay in `aitk context audit`, described in `context-audit.md`.
 
 ```bash
 aitk markdown audit
@@ -29,9 +29,9 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 The three ban sets and all six checkpoints ship with the `aitk` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same sets whether or not it installed any standards, and no file has to resolve for a run to mean something.
 
-Reading them out of the standards per run was the original design. It put a parser contract on two documents authored for people, and `prose.md` had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
+Reading them out of the standards per run was the original design. It put a parser contract on a document authored for people, and the standard had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
 
-`markdown.md` and `prose.md` still state every ban and every checkpoint, and a reader follows those rather than the code. Nothing compares the two, so a number moved in one place and left in the other drifts silently. Move both in the same change.
+`markdown.md` still states every ban and every checkpoint, and a reader follows it rather than the code. Nothing compares the two, so a number moved in one place and left in the other drifts silently. Move both in the same change.
 
 The sets are closed rather than extensible, so a project cannot add a term by editing a file. What decides that is the measurement behind them: 21 terms across 483 markdown files report a clean exit, and every occurrence of a banned word in the corpus sits inside the ban list itself or inside an example demonstrating the ban. The set is a prior an author already knows rather than a filter that has caught anything, and enumeration cannot close the gap it aims at, since `just`, `allows`, and `very` carry honest uses no literal match separates.
 
@@ -45,7 +45,7 @@ A set shipped empty is reported rather than passed. It finds nothing and would e
 
 ### Bans
 
-Three closed sets report a hit: the characters `markdown.md` bans under `## Punctuation`, the single lowercase words `prose.md` bans under `## Language`, and the British spellings of the American examples that section lists.
+Three closed sets report a hit: the characters `markdown.md` bans under `## Punctuation`, the single lowercase words it bans under `## Language`, and the British spellings of the American examples that section lists.
 
 Deriving the spellings rather than pattern-matching a suffix is what keeps `exercises`, `promises`, and `revised` out of the report. A suffix pattern over the same corpus produced 46 false positives from words of that shape, and a closed set of whole words reaches none of them.
 
@@ -120,7 +120,7 @@ Rewrite the sentence rather than swapping the banned token for a near-synonym. T
 
 A code span clears the report too, since the ban scan walks around one, and it is the answer only where the token is genuinely an identifier under discussion. `## Code and identifiers` in `markdown.md` reserves the span for commands, API names, file paths, and identifiers, so backticking a quoted utterance spends one rule to satisfy another and leaves the corpus no cleaner.
 
-A hit the closed set cannot separate from correct prose is the case with no third option. `prose.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the temporal `just` reports as the vague one. The rule as written reaches neither, and rewriting the sentence is what the toolkit settled on over building an exemption path, for the reasons below.
+A hit the closed set cannot separate from correct prose is the case with no third option. `markdown.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the temporal `just` reports as the vague one. The rule as written reaches neither, and rewriting the sentence is what the toolkit settled on over building an exemption path, for the reasons below.
 
 ### Where the rules are enforced
 
@@ -150,9 +150,9 @@ Masking took 7 of the weight-only paragraphs the checkpoint reported at 400 and
 
 ### How the ban count reached zero
 
-Eight word hits stood between the baseline and a gate, and only three carried the sense `prose.md` bans. `leverage` sat in the requirements worldview, `allows` in the claude stack reference, and one `just` was the vague qualifier in a skill body. Those three lost the qualifier rather than the word.
+Eight word hits stood between the baseline and a gate, and only three carried the sense the standard bans. `leverage` sat in the requirements worldview, `allows` in the claude stack reference, and one `just` was the vague qualifier in a skill body. Those three lost the qualifier rather than the word.
 
-The other five were correct prose the closed set cannot separate from a violation. Four were the temporal `just`, meaning a moment ago, in phrases like the implementation `just` completed and the field the user `just` edited. The fifth quoted an anti-pattern a skill exists to forbid. `prose.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the rule as written reaches none of the five while the scan reaches all of them.
+The other five were correct prose the closed set cannot separate from a violation. Four were the temporal `just`, meaning a moment ago, in phrases like the implementation `just` completed and the field the user `just` edited. The fifth quoted an anti-pattern a skill exists to forbid. `markdown.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the rule as written reaches none of the five while the scan reaches all of them.
 
 ### Why they were rewritten rather than exempted
 

package/docs/ai-workflow.md

@@ -281,6 +281,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | `aitk:toolkit-cli`         | Before a sync or install, to learn what it overwrites, merges, or leaves alone |
 | `aitk:youtube-transcripts` | When a video transcript is wanted in the repo as context                       |
 | `aitk:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress     |
+| `aitk:write-human`         | Before drafting or revising prose, for voice, rhythm, and density              |
 
 Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 

package/docs/target-projects.md

@@ -88,7 +88,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 governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/markdown.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. `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.
 

package/governance/rules/claude/500-prose.md

@@ -1,13 +1,15 @@
 ---
-description: Route markdown edits to the prose standard for voice, language, and frontmatter wording
+description: Route markdown edits to the write-human skill for voice, rhythm, sentence construction, and information density
 paths:
   - '**/*.md'
 ---
 
-# Markdown prose standards
+# Markdown voice standards
 
 ## Authority
 
-- Follow `.claude/standards/prose.md` for voice, language, and the wording of a `title` or `description`. It is the single source.
-- Read it before a substantial prose edit. Do not work the banned words from memory.
-- Punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.
+- Load the `aitk:write-human` skill for voice, rhythm, sentence construction, and information density. It is the single source for all four.
+- Load it before drafting a passage, not after revising one.
+- Report it rather than proceeding silently when the skill does not resolve.
+- Do not work these rules from memory.
+- Banned words, spellings, punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.

package/governance/rules/claude/501-markdown.md

@@ -1,5 +1,5 @@
 ---
-description: Route markdown edits to the markdown standard for headings, lists, punctuation, and file references
+description: Route markdown edits to the markdown standard for headings, lists, punctuation, banned words, and frontmatter wording
 paths:
   - '**/*.md'
 ---
@@ -8,6 +8,7 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/markdown.md` for headings, paragraph and list structure, code spans, punctuation, emphasis, and file references. It is the single source.
-- Read it before a substantial markdown edit. Do not work the banned characters from memory.
-- Voice, language, and frontmatter wording are a separate topic. `500-prose` routes them.
+- Follow `.claude/standards/markdown.md` for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, the banned words and spellings, and the wording of a `title` or `description`. It is the single source.
+- Read it before a substantial markdown edit. Do not work the banned words or characters from memory.
+- Run `aitk markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+- Voice, rhythm, and sentence construction are a separate topic. `500-prose` routes them.

package/package.json

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

package/scripts/core/install-check.sh

@@ -79,7 +79,7 @@ log_step "Assert scaffold"
 # The snippets path has to name a slug the default preset still carries, since
 # init resolves snippets through `essentials`. Editing that preset without
 # editing this line fails the gate on a correct install.
-for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/standards/prose.md" ".claude/standards/markdown.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
+for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/standards/skill.md" ".claude/standards/markdown.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/src/commands/context.ts

@@ -3,6 +3,10 @@ import type { Command } from 'commander'
 import {
   type EntryReport,
   governsContent,
+  type LengthCause,
+  type LengthFinding,
+  lengthFindings,
+  type LengthQuestion,
   LENGTH_CHECKPOINT,
   matchesSiblings,
   measureFolders,
@@ -200,6 +204,7 @@ async function runAudit(
       )
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
+  const length = gateOnly ? undefined : lengthFindings(entries)
 
   if (gateOnly) {
     reportGate(citations)
@@ -209,7 +214,7 @@ async function runAudit(
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
     reportSections(sections, folders)
-    reportLength(entries)
+    reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
     reportNarration(entries, folders, narration)
@@ -234,6 +239,16 @@ async function runAudit(
           unresolved: citations.unresolved,
         },
         entries,
+        // The join is published rather than left to a consumer, since deriving
+        // it from `entries` means restating which question the provenance count
+        // answers, and one wrong restatement is a cause reported against the
+        // wrong entry.
+        //
+        // Absent rather than empty under `--citations-only`, for the reason
+        // `checkpoints.narration` below carries. That mode measures no entry,
+        // so an empty array here reads as a corpus with nothing past the
+        // checkpoint rather than as a run that never looked.
+        length,
         missingSections: sections,
         indexDrift: drift,
         checkpoints: {
@@ -475,7 +490,32 @@ function reportSections(
   )
 }
 
-function reportLength(entries: readonly EntryReport[]): void {
+/** How each question reads in the report, in the standard's own order. */
+const QUESTION_LABEL: Record<LengthQuestion, string> = {
+  domain: 'one domain',
+  reproduced: 'reproduced content',
+  history: 'own history',
+}
+
+function readCause(cause: LengthCause): string {
+  const label = QUESTION_LABEL[cause.question]
+
+  if (cause.state === 'unanswered') return `${label}: open`
+  if (cause.state === 'no') return `${label}: no`
+
+  return `${label}: yes, ${plural(cause.markers ?? 0, 'marker')}`
+}
+
+/**
+ * Names each entry past the checkpoint with the three questions the standard
+ * asks of it, rather than a count a reader has to cross-reference by eye.
+ *
+ * The checkpoint is not a cap, so the legend says what the list is for. An
+ * entry that answers all three and is still long is a correct outcome under a
+ * standard stating there is no hard cap, and a run reporting success as a
+ * smaller count would have adopted the number the standard declines.
+ */
+function reportLength(over: readonly LengthFinding[]): void {
   logStep('Length')
   logInfo(
     `Entries measure rendered lines at ${RENDER_WIDTH} columns, counting frontmatter and fenced blocks.`,
@@ -484,19 +524,26 @@ function reportLength(entries: readonly EntryReport[]): void {
     'A reference-heavy entry therefore ranks by its examples, which the depth check in `aitk markdown audit` excludes.',
   )
 
-  const over = entries
-    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
-    .sort((a, b) => b.lines - a.lines)
-
   if (over.length === 0) {
     logInfo(`No entry past the ${LENGTH_CHECKPOINT}-line checkpoint.`)
     return
   }
 
   logWarn(`${over.length} past the ${LENGTH_CHECKPOINT}-line checkpoint`)
+  logInfo(
+    'The checkpoint is not a cap. Each entry carries the three questions the standard asks past it, and the fix goes to whichever is true.',
+  )
+  logInfo(
+    'Own history is answered from the provenance markers below. The other two are judgments no measure settles, so they stay open for a reader.',
+  )
   pipeOutput(
     over
-      .map((entry) => `${entry.rel}  ${entry.lines} rendered lines`)
+      .map(
+        (finding) =>
+          `${finding.rel}  ${finding.lines} rendered lines\n  ${finding.causes
+            .map(readCause)
+            .join('  ')}`,
+      )
       .join('\n'),
   )
 }

package/src/commands/markdown.ts

@@ -87,8 +87,8 @@ export function register(program: Command): void {
         '',
         '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',
+        'measured the same as one that did. markdown.md still states 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:',

package/src/comments/vocabulary.ts

@@ -57,7 +57,7 @@ export function parseVocabulary(markdown: string): string[] | undefined {
  *
  * Reading the list out of the rule rather than hardcoding it is what keeps one
  * definition when the rule installs into a target, the same way
- * `.claude/hooks/standards-audit.sh` reads its word bans out of `prose.md`.
+ * `aitk markdown audit` owns one copy of the ban sets for every caller.
  */
 export async function loadVocabulary(root: string): Promise<Vocabulary> {
   for (const ruleRoot of RULE_ROOTS) {

package/src/context/audit.ts

@@ -166,6 +166,52 @@ export interface EntryReport {
    * exempt from owing sections rather than from being well formed.
    */
   readonly stub: boolean
+  /**
+   * Whether a content rule reached this entry, which is what parts an empty
+   * `provenance` list that was measured from one that was never scanned. The
+   * length finding reads it, since reporting a clean history for an entry
+   * outside the governed folder answers a question nothing asked.
+   */
+  readonly governed: boolean
+}
+
+/**
+ * The three questions `standards/context.md` asks of an entry past the
+ * checkpoint, in the order it states them.
+ *
+ * The standard calls no entry over the checkpoint wrong. It asks whether the
+ * entry still covers a single domain, whether it has filled with content `ls`
+ * or `--help` reproduces, and whether it has accumulated the history of its own
+ * changes, then directs a fix at whichever is true. A report naming the count
+ * alone leaves all three unasked, which is why the finding carries them.
+ */
+export type LengthQuestion = 'domain' | 'reproduced' | 'history'
+
+/**
+ * What the audit can say about one question for one entry.
+ *
+ * `unanswered` is a state rather than an omission. Two of the three questions
+ * are judgments no measure settles, and dropping them would read as an entry
+ * nothing found rather than one nothing checked.
+ */
+export type QuestionState = 'yes' | 'no' | 'unanswered'
+
+export interface LengthCause {
+  readonly question: LengthQuestion
+  readonly state: QuestionState
+  /**
+   * Markers behind a `yes`, and absent wherever nothing was counted. It cites
+   * the provenance finding rather than restating it, so the two sections of the
+   * report describe the same measurement once.
+   */
+  readonly markers?: number
+}
+
+export interface LengthFinding {
+  readonly rel: string
+  readonly lines: number
+  /** One entry per question in `LengthQuestion` order, never empty. */
+  readonly causes: readonly LengthCause[]
 }
 
 export interface SectionFinding {
@@ -481,9 +527,52 @@ export function measureEntry(
     bareReferences: bareReferences(lines, siblings),
     sections: governsContent ? declaredSections(lines) : [],
     stub: isStubSeed(source),
+    governed: governsContent,
   }
 }
 
+/**
+ * Names each entry past the checkpoint with the standard's three questions
+ * answered as far as anything measures them.
+ *
+ * Only accumulated history is mechanical, and it is already measured by the
+ * provenance check, so this joins that count rather than counting again. The
+ * other two are read by a person: whether an entry still covers one domain is a
+ * judgment about its subject, and recognizing content `ls` or `--help`
+ * reproduces needs a reader who knows what those emit.
+ *
+ * An entry outside the governed folder has no measured question at all, since
+ * provenance is scoped to the standard stating it, and reporting `no` there
+ * would answer from a scan that never ran.
+ *
+ * Sorted longest first, which is the order the report already printed and the
+ * order the questions are worth asking in.
+ */
+export function lengthFindings(
+  entries: readonly EntryReport[],
+): LengthFinding[] {
+  return entries
+    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
+    .sort((a, b) => b.lines - a.lines)
+    .map((entry) => ({
+      rel: entry.rel,
+      lines: entry.lines,
+      causes: [
+        { question: 'domain', state: 'unanswered' },
+        { question: 'reproduced', state: 'unanswered' },
+        historyCause(entry),
+      ] satisfies LengthCause[],
+    }))
+}
+
+function historyCause(entry: EntryReport): LengthCause {
+  if (!entry.governed) return { question: 'history', state: 'unanswered' }
+
+  return entry.provenance.length > 0
+    ? { question: 'history', state: 'yes', markers: entry.provenance.length }
+    : { question: 'history', state: 'no' }
+}
+
 /**
  * Measures every entry in the audited folders. A generated `index.md` is not
  * among them, since its body is rewritten on every regen and no checkpoint

package/src/markdown/bans.ts

@@ -10,7 +10,7 @@ import type { BanSets } from '@/markdown/scan'
 const CHARACTERS = ['—', ';'] as const
 
 /**
- * Single lowercase words `prose.md` bans under `## Language`.
+ * Single lowercase words `markdown.md` bans under `## Language`.
  *
  * A multi-word ban is absent by the same test the character set applies. The
  * standard bans a pattern like `It's not X, it's Y` with a placeholder standing
@@ -34,7 +34,7 @@ const WORDS = [
 ] as const
 
 /**
- * British spellings of the American examples `prose.md` lists.
+ * British spellings of the American examples `markdown.md` lists.
  *
  * The set is carried whole rather than derived from a suffix rule, because a
  * suffix pattern run over prose produced 46 of the 58 false positives measured

package/src/standards/closure.ts

@@ -29,7 +29,7 @@ const CITATION = /`([^`\n]+?\.md)`/g
 const DELEGATION_START = /^Does not govern:/
 const HEADING = /^#{1,6}\s/
 
-/** Accepts `prose` and `prose.md` alike, since the catalog lists both spellings. */
+/** Accepts `skill` and `skill.md` alike, since the catalog lists both spellings. */
 export function normalizeName(raw: string): string {
   const name = raw.trim()
   return name.endsWith('.md') ? name : `${name}.md`

package/standards/bundled/issue.md

@@ -14,8 +14,8 @@ Does not govern:
 
 - Pull request title and body: `pr.md`
 - Whether a phase label may appear in issue text: `versioning.md`
-- Voice and banned words in issue prose: `prose.md`
-- Punctuation and formatting in issue prose: `markdown.md`
+- Voice, rhythm, and sentence construction in issue prose: the `write-human` skill
+- Punctuation, formatting, and banned words in issue prose: `markdown.md`
 
 ## Title
 

package/standards/bundled/pr.md

@@ -15,8 +15,8 @@ Does not govern:
 - Commit subject format, which shares the title form: `commit.md`
 - Branch naming: `branch.md`
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Voice and banned words in pull request prose: `prose.md`
-- Punctuation and formatting in pull request prose: `markdown.md`
+- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
+- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
 
 ## Title
 

package/standards/bundled/snippets.md

@@ -13,8 +13,8 @@ Governs a snippet file: what one is for, whether a prompt qualifies as one, how
 Does not govern:
 
 - Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
-- Voice and word choice in snippet prose: `prose.md`
-- Punctuation and formatting in snippet prose: `markdown.md`
+- Voice, rhythm, and sentence construction in snippet prose: the `write-human` skill
+- Punctuation, formatting, and word choice in snippet prose: `markdown.md`
 
 ## What a snippet is
 

package/standards/diagrams.md

@@ -11,12 +11,12 @@ A diagram entry answers one question about the system with one or more Mermaid d
 
 ## Scope
 
-Governs per-kind diagram entries under `.claude/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield `prose.md` grants a surface whose own standard sets one.
+Governs per-kind diagram entries under `.claude/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield the `write-human` skill grants a surface whose own standard sets one.
 
 Does not govern:
 
-- Language and word choice in explanation prose and node labels: `prose.md`, whose bans the yield does not lift
-- Punctuation and formatting in explanation prose: `markdown.md`, which the yield does not reach
+- Rhythm and sentence construction in explanation prose: the `write-human` skill, whose rules the yield does not lift beyond voice
+- Language, word choice, punctuation, and formatting in explanation prose and node labels: `markdown.md`, which the yield does not reach
 - The mechanism behind any component a diagram draws: `context.md`
 - UI layout, on-screen copy, and interaction intent: `wireframes.md`
 - The decision record a components diagram is drawn from: `architecture.md`
@@ -94,7 +94,7 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 - Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
 - The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
 
-This section states the voice for the surface, which is what claims the yield `prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. The language bans in `prose.md` stay in force, as do the punctuation and formatting rules in `markdown.md`, which grants no yield at all.
+This section states the voice for the surface, which is what claims the yield the `write-human` skill grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the language bans, punctuation, and formatting in `markdown.md`, which grants no yield at all.
 
 ## Verification
 
@@ -121,7 +121,7 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
 - The `claude-docs` sweep watches two things and writes frontmatter only. It appends `stale` when a path an entry cites leaves the tree, and it stubs a kind when a diff adds the source signal that kind is drawn from. Diagram bodies and explanation paragraphs are off limits to it, because a change that removes a module does not carry the new correct shape of the picture.
 - That watch samples thinly. It sees the one or two paths an entry happened to cite and nothing else, so a change elsewhere leaves the entry looking current. `verified` is what covers the gap, and an entry whose date sits far behind the branch is due a read whether or not anything flagged it.
-- The explanation paragraphs around a Mermaid block are prose and follow `prose.md` and `markdown.md`. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
+- The explanation paragraphs around a Mermaid block are prose and follow `markdown.md` and the `write-human` skill. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
 - The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.
 
 ## Template

package/standards/glossary.md

@@ -15,8 +15,8 @@ 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 and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 
 ## What a working glossary looks like
 

package/standards/groundwork.md

@@ -18,8 +18,8 @@ Does not govern:
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The feature plan a closed track feeds, and the contract its answer slots keep: `plan.md`
 - The task file a closing track writes, and the origin line pointing back at the folder: `tasks.md`
-- Voice and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 - When a project opens a track at all, and the procedure that runs one, which belong to the surface driving it
 
 ## What a working track looks like

package/standards/index.md

@@ -14,10 +14,9 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [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, and file references
+- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
-- [Prose reference](prose.md): Voice, language, what prose may claim, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md

package/standards/intake.md

@@ -18,8 +18,8 @@ Does not govern:
 - One question measured in depth before anyone can plan against it: `groundwork.md`
 - The feature plan a promoted item feeds, and the inverted answer contract it keeps: `plan.md`
 - The task file promoting an item onto the board, and the origin line pointing back at the folder: `tasks.md`
-- Voice and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 - Which findings belong in a dump at all, and the procedure that files one, which belong to the surface driving it
 
 ## What a working intake looks like

package/standards/markdown.md

@@ -1,22 +1,28 @@
 ---
 title: Markdown reference
-description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
 ---
 
 # Markdown reference
 
-Applies to markdown reference docs, READMEs, and inline documentation in repos. These are mechanics rather than voice, so no surface yields them. A surface stating its own voice claims that yield from `prose.md` and formats by this file regardless.
+Applies to markdown reference docs, READMEs, and inline documentation in repos. Every rule here is a fact a scan can settle rather than a judgment, so no surface yields any of them. A surface stating its own voice claims that yield from the voice guidance and formats and spells by this file regardless.
 
 ## Scope
 
-Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have no shape of their own.
+Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the closed-set word and spelling bans, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
+
+The two frontmatter fields it reaches are `title` and `description`. They are named here rather than in the statement above, since a backticked token in a scope statement's first sentence is published as the standard's jurisdiction.
+
+The split with the voice guidance is what reads the rule rather than what the rule covers. Every ban below ships as data `aitk markdown audit` and the installed audit hook both read, so a violation is measured on every run. Cadence, rhythm, and information density are judgments a reader settles, and those travel in the `write-human` skill, which a markdown edit routes to.
 
 Does not govern:
 
-- Voice, word choice, what prose may claim, and the wording of a `title` or `description`: `prose.md`
+- Voice, rhythm, sentence construction, and information density, which the `write-human` skill carries
 - What sections a document has, or what belongs in each: the standard for that document type
+- Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
 - The text inside a fenced block, which follows the conventions of its own language rather than these
-- The scan that applies the punctuation bans to finished text on its way out: `publish.md`
+- Phase-label and semver discipline: `versioning.md`
+- The scan that applies these bans to finished text on its way out: `publish.md`
 - Whether a pull request or issue number is backticked, which turns on where the text is published rather than on the text: `publish.md`
 
 ## Headings
@@ -58,7 +64,30 @@ Does not govern:
 - Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them.
 - Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
 
-The closed-set word bans sit in `prose.md` under `## Language` rather than here, because a banned word is a word-choice rule and these are character rules. A surface applying both reads both files.
+## Language
+
+- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
+- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
+- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
+- Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
+- Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
+- Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
+- Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
+- Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
+- Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
+- Do not name a person, company, or product to borrow its authority. Name a source only where the claim turns on who made it.
+- Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
+- Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
+
+The word bans and the character bans sit under one file because one command reads both. `aitk markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this section states them for a reader rather than for the parser.
+
+## Frontmatter descriptions
+
+When frontmatter carries a short `title` or `description` used for catalog display:
+
+- `title`: sentence case, identifies the file uniquely against its siblings in the same catalog. Proper nouns retain their casing. No trailing period.
+- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. Lead with concrete subjects, strip filler like "guide to", "overview of", or "documentation about". No trailing period, no leading article (`the`, `a`).
+- Do not mechanically reuse the H1 as the description.
 
 ## Emphasis and dividers
 
@@ -83,3 +112,23 @@ Good: See `.claude/context/retrieval.md` for the retrieval flow.
 Bad: Read [docs/development.md](docs/development.md) before contributing.
 Good: Read the [development guide](docs/development.md) before contributing.
 ```
+
+```markdown
+Bad: In order to configure the server, you'll need to ensure that the port is set.
+Good: Set `port` in the server config.
+```
+
+```markdown
+Bad: It's not just a cache. It's a system for intelligent memory management.
+Good: The cache is an LRU store. It evicts the least-recently-used entry when full.
+```
+
+```markdown
+Bad: Leveraging the retry mechanism, developers can build more resilient integrations.
+Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
+```
+
+```markdown
+Bad: It might be worth considering whether to enable caching.
+Good: Enable caching for read-heavy endpoints. Skip it for writes.
+```