@erclx/aitk 0.104.1 → 0.106.0

package/src/gov/test-order.ts

@@ -0,0 +1,383 @@
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * Preferred first, matching `src/tasks/trunk.ts`. A clone with no remote still
+ * answers off its local trunk, and a local `main` trailing the remote widens
+ * the range rather than narrowing it, which over-reports instead of hiding.
+ */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/**
+ * The extensions this check can pair. A test sits beside its subject under one
+ * name throughout this corpus, so the weakest assumption available is also the
+ * one the corpus already honors. Every other extension is read past and named,
+ * since a bash script and its test are related by nothing a filename carries.
+ */
+export const SOURCE_EXTENSIONS = ['.ts', '.tsx'] as const
+
+/** The suffix removed to derive the subject a test covers. */
+export const TEST_SUFFIXES = ['.test.ts', '.test.tsx'] as const
+
+/** A `%H` line, which is 40 hex characters under sha1 and 64 under sha256. */
+const COMMIT = /^[0-9a-f]{40,64}$/
+
+/** A `--name-status` line: a status letter, a tab, then one path. */
+const NAME_STATUS = /^([A-Z])\d*\t(.+)$/
+
+export type Verdict = 'satisfied' | 'implementation-first' | 'unclassified'
+
+export interface PairRecord {
+  /** The implementation path, which is what a subject is named by. */
+  readonly subject: string
+  /** The test paired to it, or `null` when the pairing found no partner. */
+  readonly test: string | null
+  readonly verdict: Verdict
+  readonly implementationCommit: string | null
+  readonly testCommit: string | null
+  /** Why the verdict reads the way it does, in the report's own words. */
+  readonly reason: string
+}
+
+export interface Scope {
+  readonly extensions: readonly string[]
+  readonly testSuffixes: readonly string[]
+}
+
+export type TestOrderReport =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly head: string
+      readonly scope: Scope
+      readonly satisfied: readonly PairRecord[]
+      readonly findings: readonly PairRecord[]
+      readonly unclassified: readonly PairRecord[]
+      /** Changed paths outside the pairing's reach, named rather than counted. */
+      readonly ignored: readonly string[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+export interface TestOrderOptions {
+  /** The far side of the range, defaulting to the merge base against the trunk. */
+  readonly base?: string
+}
+
+/** One path as one commit in the range touched it. */
+interface Change {
+  readonly path: string
+  readonly status: string
+  readonly commit: string
+  /** Position in the range, oldest first, which is what orders a pair. */
+  readonly order: number
+}
+
+/**
+ * Reads `--name-status` log output, oldest commit first, into one entry per
+ * path per commit.
+ *
+ * The order field rather than the commit is what a comparison reads, since two
+ * commits carry no ordering a caller can derive from their hashes alone.
+ */
+function parseChanges(output: string): Change[] {
+  const changes: Change[] = []
+  let commit = ''
+  let order = -1
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trimEnd()
+    if (trimmed === '') continue
+
+    if (COMMIT.test(trimmed)) {
+      commit = trimmed
+      order += 1
+      continue
+    }
+
+    const match = NAME_STATUS.exec(trimmed)
+    if (match === null || commit === '') continue
+
+    changes.push({ path: match[2], status: match[1], commit, order })
+  }
+
+  return changes
+}
+
+/** Whether a path is a test this check can derive a subject from. */
+function testSuffix(path: string): string | undefined {
+  return TEST_SUFFIXES.find((suffix) => path.endsWith(suffix))
+}
+
+/**
+ * The implementation a test covers, derived by removing the test suffix.
+ *
+ * A behavior split across two modules pairs wrongly or not at all under this,
+ * which is what the unclassified bucket exists to catch rather than hide.
+ */
+function subjectOf(path: string): string {
+  const suffix = testSuffix(path)
+  if (suffix === undefined) return path
+  return `${path.slice(0, -suffix.length)}${suffix.replace('.test', '')}`
+}
+
+/** The one test path that would cover `subject` under the beside convention. */
+function testPathFor(subject: string): string {
+  return subject.replace(/\.(tsx?)$/, '.test.$1')
+}
+
+/**
+ * Whether a path is an implementation this check can pair. A declaration file
+ * carries no behavior to test, so it is read past rather than reported as a
+ * module nothing covers.
+ */
+function isImplementation(path: string): boolean {
+  if (path.endsWith('.d.ts')) return false
+  if (testSuffix(path) !== undefined) return false
+  return SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension))
+}
+
+/** The first commit in the range that added `path`, or `undefined`. */
+function introduction(
+  changes: readonly Change[],
+  path: string,
+): Change | undefined {
+  return changes.find((change) => change.path === path && change.status === 'A')
+}
+
+function classify(
+  changes: readonly Change[],
+  atBase: ReadonlySet<string>,
+): {
+  satisfied: PairRecord[]
+  findings: PairRecord[]
+  unclassified: PairRecord[]
+} {
+  const satisfied: PairRecord[] = []
+  const findings: PairRecord[] = []
+  const unclassified: PairRecord[] = []
+
+  // Keyed by subject so a module whose implementation and test both moved is
+  // one record rather than two, and so a test with no partner still reports
+  // under the implementation path a reader would go looking for.
+  const subjects = new Set<string>()
+  for (const change of changes) {
+    if (isImplementation(change.path)) subjects.add(change.path)
+    else if (testSuffix(change.path) !== undefined) {
+      subjects.add(subjectOf(change.path))
+    }
+  }
+
+  for (const subject of [...subjects].sort()) {
+    const candidate = testPathFor(subject)
+    const testChange = introduction(changes, candidate)
+    const testAtBase = atBase.has(candidate)
+    const test = testAtBase || testChange !== undefined ? candidate : undefined
+
+    const implementation = introduction(changes, subject)
+
+    if (implementation === undefined) {
+      unclassified.push({
+        subject,
+        test: test ?? null,
+        verdict: 'unclassified',
+        implementationCommit: null,
+        testCommit: null,
+        reason: atBase.has(subject)
+          ? 'the implementation predates the range, so a change to it cannot be separated from a refactor'
+          : 'no implementation reached the range beside this test',
+      })
+      continue
+    }
+
+    if (test === undefined) {
+      unclassified.push({
+        subject,
+        test: null,
+        verdict: 'unclassified',
+        implementationCommit: implementation.commit,
+        testCommit: null,
+        reason: 'no test names this module, so the ordering has no second side',
+      })
+      continue
+    }
+
+    // A paired test the range never added is one that already sat at the base
+    // commit, since those are the only two ways `test` gets a value at all.
+    if (testChange === undefined) {
+      satisfied.push({
+        subject,
+        test,
+        verdict: 'satisfied',
+        implementationCommit: implementation.commit,
+        testCommit: null,
+        reason: 'the test predates the range',
+      })
+      continue
+    }
+
+    // One commit carrying both sides counts as satisfied. The rule asks that
+    // the test not come after, and a single commit is the shape a small change
+    // takes here, so reporting it would flag most of the corpus.
+    const record: PairRecord = {
+      subject,
+      test,
+      verdict:
+        testChange.order <= implementation.order
+          ? 'satisfied'
+          : 'implementation-first',
+      implementationCommit: implementation.commit,
+      testCommit: testChange.commit,
+      reason:
+        testChange.order <= implementation.order
+          ? 'the test reached history no later than the implementation'
+          : 'the implementation reached history before the test covering it',
+    }
+
+    if (record.verdict === 'satisfied') satisfied.push(record)
+    else findings.push(record)
+  }
+
+  return { satisfied, findings, unclassified }
+}
+
+/**
+ * Where an implementation reached a commit ahead of the test covering it,
+ * between `base` and the current `HEAD` of the tree at `root`.
+ *
+ * This reports and never gates. Pairing a test to an implementation is a
+ * judgment, so a change the pairing cannot read lands in `unclassified` with
+ * its reason stated rather than being counted as a pass. Coverage is narrower
+ * than the rule the check answers to, and `scope` and `ignored` are what say so
+ * on every run.
+ */
+export function readTestOrder(
+  root: string,
+  options: TestOrderOptions = {},
+): TestOrderReport {
+  const head = revParse(root, 'HEAD')
+  if (head === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
+    }
+  }
+
+  const base = resolveBase(root, options.base, head)
+  if (typeof base !== 'string') return base
+
+  const log = git(root, [
+    'log',
+    '--reverse',
+    '--name-status',
+    '--no-renames',
+    '--format=%H',
+    `${base}..${head}`,
+  ])
+
+  if (log === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading history between ${base} and HEAD failed under ${root}.`,
+    }
+  }
+
+  const tree = git(root, ['ls-tree', '-r', '--name-only', base])
+  if (tree === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
+    }
+  }
+
+  const changes = parseChanges(log)
+  const atBase = new Set(tree.split('\n').filter((line) => line !== ''))
+
+  const ignored = [
+    ...new Set(
+      changes
+        .map((change) => change.path)
+        .filter(
+          (path) => !isImplementation(path) && testSuffix(path) === undefined,
+        ),
+    ),
+  ].sort()
+
+  return {
+    kind: 'measured',
+    base,
+    head,
+    scope: { extensions: SOURCE_EXTENSIONS, testSuffixes: TEST_SUFFIXES },
+    ...classify(changes, atBase),
+    ignored,
+  }
+}
+
+/**
+ * The far side of the range. A ref the caller named has to resolve, since
+ * falling back to the trunk there would measure a range nobody asked for. With
+ * no ref named, the merge base against the trunk scopes the run to the branch,
+ * and a repository carrying no trunk falls back to the root commit rather than
+ * refusing.
+ */
+function resolveBase(
+  root: string,
+  ref: string | undefined,
+  head: string,
+): string | { kind: 'unreadable'; reason: string } {
+  if (ref !== undefined) {
+    const resolved = revParse(root, ref)
+    if (resolved === undefined) {
+      return {
+        kind: 'unreadable',
+        reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+      }
+    }
+    return resolved
+  }
+
+  for (const trunk of TRUNK_REFS) {
+    if (revParse(root, trunk) === undefined) continue
+    const merged = git(root, ['merge-base', head, trunk])
+    if (merged !== undefined && merged !== '') return merged
+  }
+
+  const rootCommits = git(root, ['rev-list', '--max-parents=0', head])
+  if (rootCommits === undefined || rootCommits === '') {
+    return {
+      kind: 'unreadable',
+      reason: `No base resolves against ${root}. Fetch origin or pass --base.`,
+    }
+  }
+
+  return rootCommits.split('\n')[0]
+}
+
+/**
+ * `execaSync` with git's repository-resolution variables stripped, so `-C`
+ * resolves against `root` and not against whatever repository a hook exported.
+ * `undefined` is the refusal, which every caller turns into its own reason.
+ */
+function git(root: string, args: readonly string[]): string | undefined {
+  const result = execaSync('git', ['-C', root, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  return result.exitCode === 0 ? result.stdout.trimEnd() : undefined
+}
+
+/**
+ * The commit a ref names. `^{commit}` is what turns a tag or a tree into the
+ * commit behind it, so a caller never compares a ref against another type.
+ */
+function revParse(root: string, ref: string): string | undefined {
+  const resolved = git(root, [
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${ref}^{commit}`,
+  ])
+
+  return resolved === undefined || resolved === '' ? undefined : resolved.trim()
+}

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
@@ -122,6 +122,10 @@ Each spike carries four things:
 
 Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
 
+A spike also leaves files behind, and they split on whether the track cites them rather than on whether they are markdown. An input the run reads, being a fixture page, an arm script, or a copied asset, is re-runnable and cited by nothing, so it stays outside the track wherever the surface driving the spike puts it. Evidence the record cites, being a recording, a render, or a frame pulled from one, is what a later reader opens to check a claim, so it lives in `evidence/` inside the track beside the file citing it. Name the split rather than the file types, which is what keeps this from going stale on the next kind of artifact a spike produces.
+
+`evidence/` takes no number, since numbering is the read order over the files a reader opens in sequence and an artifact is reached from the claim that cites it instead.
+
 Reach for a test harness the project already carries before building one. A track needing an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
 
 One method error is worth naming, because it is made rather than imagined. Counting matches in a transcript overstates whether a file was read, since an instruction naming a path puts that path in the transcript whether or not anything opened it. The check is the tool call.

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.
+```

package/standards/memory.md

@@ -18,8 +18,8 @@ Does not govern:
 - The per-domain entry a domain fact is routed to instead of memory: `context.md`
 - The feature plan a session executes, and its answer contract: `plan.md`
 - The task file tracking what is being built: `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 facts a project captures at all, and where the folder sits, which are project policy
 
 ## What a working entry looks like

package/standards/plan.md

@@ -19,8 +19,8 @@ Does not govern:
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
 - The transform from a branch name to a slug: `slug.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 plan is written at all, and whether a short one goes to a file or to the conversation, which belong to the surface driving it
 
 ## What a working plan looks like