@erclx/aitk 0.107.2 → 0.108.0

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

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

package/docs/agents/markdown-audit.md

@@ -27,7 +27,9 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 ## Where the rules come from
 
-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.
+The three ban sets and all nine 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.
+
+Six of the nine are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
 
 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.
 
@@ -98,9 +100,29 @@ That re-sample ran once the scan stopped counting link syntax as prose. Findings
 
 A bullet, a heading, a table row, a blockquote, a blank line, and a fence each end a paragraph, so a heavy bullet is reported by the bullet check alone and never counted twice.
 
+### Cadence
+
+Uniform cadence is the failure a ban list cannot express. A ban set states negatives, and fragments, verbless clauses, and sentences that all run one length are each the absence of something, so no addition to the thirteen banned words reaches any of them. The shape layer already measured a bullet, a paragraph, and a run, and stopped one level above where that failure lives.
+
+Cadence measures a paragraph on two numbers. The spread is the words between its longest and shortest sentence, and the opener count is the times one word opens a sentence in it. A spread of five words or under reads as one cadence, and a word opening more than two sentences is a pattern rather than a coincidence. Both come from `## Rhythm` in the `write-human` skill, which states them about prose a person reads, and this measures against that statement rather than setting a threshold of its own.
+
+Words are counted off the text a reader is shown. A link contributes its anchor text, an autolink contributes nothing, and the sentence boundaries do not move under that masking, since the boundary pattern requires whitespace after the terminal punctuation and no destination carries any. An opening word is lowercased and stripped of punctuation, so a sentence opening on a backticked command name reports the command.
+
+A paragraph carrying fewer than three sentences is skipped rather than scored. A two-sentence configuration note has no spread worth reading, and the opener rule is written about a third sentence turning a coincidence into a pattern, so neither number says anything before the floor. That is the cheap form of a wider exemption: a shape-aware one, exempting a short reference block by what it is rather than by how many sentences it holds, waits on a second case.
+
+The unit is the paragraph and each file names its worst on each measure, which follows the depth check rather than setting a precedent. A file's flattest paragraph and its most repetitive one are named only when each crosses its checkpoint, so a file reading healthy names nothing rather than offering its least healthy paragraph as a finding.
+
+Neither number gates and neither names a file wrong. This is a weaker claim than the one the weight checkpoints make, because a healthy range differs by surface: a catalog entry is several short sentences carrying one fact each, and a page arguing a decision is not, so one range applied across the corpus would report the surfaces that are correct. The run therefore states where the numbers came from beside them, and the counts are what a reader compares against.
+
+Measured at `6c273324` across the corpus, 2119 paragraphs reached the floor, 165 sat at or under the spread checkpoint and 50 past the opener checkpoint. Over the 60 files carrying at least ten measured paragraphs the flat rate runs from zero to 21 percent with a median near 6, which is the spread that makes the measure worth reading. Two wiki pages sit at either end of it: a server catalog reports 19 percent, its flattest paragraph five sentences within four words of each other and three of them verbless, while a page arguing where the prose rules came from reports none.
+
+That reading travels with the command rather than staying here. `BASELINE` in `src/markdown/structure.ts` carries the overall share, the per-file range, and the ten-paragraph floor beneath which a file's own rate says nothing, and the run prints all four in the legend beside the rate it measured. A count with no range beside it reads as a finding, and naming that a healthy range differs by surface states that a range exists rather than what it looks like. This page is toolkit-internal, so a reader running the command in a project that installed no standards would otherwise have two counts and nothing to place them against.
+
+Two of the rules `write-human` states are deliberately not implemented. A sentence's grammatical shape and whether it carries a finite verb each need a parse rather than a match, and an imperative or a heading fragment would read as a defect under a pattern that approximated either. The verbless share is the measure closest to the reported symptom, which is exactly why shipping it wrong would discredit the two that hold. It ships when something can identify a finite verb rather than guess at one.
+
 ## Exit codes
 
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling fails the run. Bullet, paragraph, and depth weight are judgments a reader settles, so all three report under every code.
+Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling fails the run. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
 
 `3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `scripts/core/verify.sh` is right to warn and skip. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 

package/docs/agents/skills-audit.md

@@ -67,7 +67,11 @@ aitk claude skills drift 02d7b265 --json
 | -------- | ---------------------------------------------------------- |
 | `--json` | Add a machine-readable record on stdout, keeping the frame |
 
-A skill body enters a session once and stays. Re-invoking the skill replays the copy the session already holds rather than re-reading the file, so a session that outlives a merge touching a body it loaded keeps applying what it loaded and nothing compares the two. A compaction carries the held copy forward with the summary it writes, which makes the exposure the age of the oldest load rather than the age of the session.
+A skill body enters a session once and stays. Re-invoking the skill does not re-read the file, so an edit made this session is not picked up and nothing compares the two. A session that outlives a merge touching a body it loaded keeps applying what it loaded, and a compaction carries the held copy forward with the summary it writes, which makes that exposure the age of the oldest load rather than the age of the session.
+
+Age is one route and not the only one. A session that edits a body and then invokes that same skill later in the same run replays the pre-edit text, which is what a ship chain does whenever a branch touches a body the chain runs at the end. This verb does not reach that route, because it reads history and the edit is still uncommitted when the replay happens. Re-read a body after editing it, and do not wait for a report to name it.
+
+Which shape the staleness takes decides whether anyone notices. A held body naming a file the branch deleted fails loudly by having nothing to read. One naming a file that still exists while saying something different resolves and reads current, so the session applies the stale rule and reports success.
 
 The ref is required and carries no default. `HEAD` is the only value the command could supply for itself, and it answers every run with nothing moved, which is the silence this verb exists to break. A session passes the commit it started from.
 
@@ -83,6 +87,8 @@ The report names the newest commit that rewrote each body rather than the first,
 
 The report says a file moved, not that a session holds a stale copy. A session cannot read its own loaded body as bytes, so the comparison runs against history and a ref older than the oldest load over-reports. That is the safe direction, since confirming a name costs one read of the body while the failure being answered is silence. Every run states the bound, including the run that names nothing.
 
+The verb answers only when someone runs it, and a report read is not a report acted on. A session that sees a moved body in the result and does not re-read that body stands where it started. One session reached that outcome after running the verb at session start, then followed the held copy for the rest of the day.
+
 Two cases fall outside the range. An uncommitted edit in the working tree is not history yet, so a body changed and left unstaged reports as unmoved. A target project loads the plugin from a marketplace cache with no repository behind it, where the verb refuses and names the absent history rather than reporting a clean tree.
 
 Exit codes are `0` when history was read, whether or not a body moved, and `1` when the question could not be answered. An absent shipped corpus, an absent repository, and a ref matching no commit each refuse with their own reason on stderr. A command exiting zero on a question it never answered is the failure `.claude/ARCHITECTURE.md` already records against two skills, which is why no path here reports an empty result in place of a refusal.

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

@@ -13,6 +13,11 @@ paths:
 
 - Read the skill's sibling `REQUIREMENT.md` when one exists. If the change closes no gap it states, change the requirement first or drop the change.
 
+## After editing
+
+- Re-read a skill body this session edited before invoking that skill again in the same session
+- Do not read a resolved file path in a held body as evidence the body is current
+
 ## 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.

package/package.json

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

package/src/commands/markdown.ts

@@ -11,6 +11,7 @@ import {
   scanBans,
 } from '@/markdown/scan'
 import {
+  BASELINE,
   CHECKPOINTS,
   type Checkpoints,
   measureStructure,
@@ -58,7 +59,7 @@ export function register(program: Command): void {
   markdown
     .command('audit')
     .description(
-      'Fail on a banned character, word, or spelling, and report bullet, paragraph, and depth weight',
+      'Fail on a banned character, word, or spelling, and report bullet, paragraph, cadence, and depth',
     )
     .argument(
       '[path...]',
@@ -80,6 +81,10 @@ export function register(program: Command): void {
         'depth weight are judgments a reader settles, so all three report and',
         'none of them fails a run.',
         '',
+        'Cadence reports the same way and carries one more caveat. Its range is',
+        'drawn from prose a person reads, so terse reference prose sits below',
+        'it correctly and a flat paragraph there is not a defect.',
+        '',
         'Rewrite the sentence carrying a hit rather than swapping the token for',
         'a near-synonym. A code span clears the report and is the answer only',
         'where the token is genuinely an identifier under discussion, which is',
@@ -146,6 +151,7 @@ async function runAudit(
   reportBans(reports, bans, empty)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
+  reportCadence(reports, checkpoints)
   reportDepth(reports, checkpoints)
   outro()
 
@@ -168,6 +174,9 @@ async function runAudit(
           paragraph: checkpoints.paragraph,
           sentences: checkpoints.sentences,
           renderWidth: checkpoints.renderWidth,
+          cadence: checkpoints.cadence,
+          spread: checkpoints.spread,
+          opener: checkpoints.opener,
         },
         entries: reports.map((report) => ({
           path: report.rel,
@@ -176,6 +185,7 @@ async function runAudit(
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
           heavyParagraphs: report.structure.heavyParagraphs,
+          cadence: report.structure.cadence,
         })),
       })}\n`,
     )
@@ -377,6 +387,99 @@ function reportParagraphs(
   )
 }
 
+/**
+ * Reports the distribution rather than a verdict, which is what separates this
+ * step from the three above it.
+ *
+ * Bullet, paragraph, and depth weight each report a count against a checkpoint
+ * a reader settles. Cadence reports a count as well, and the range behind it is
+ * drawn from one surface class rather than from the corpus, so the step states
+ * where the numbers came from beside them. A reader whose file is terse
+ * reference prose is meant to read a flat paragraph as correct, and a number
+ * printed with no comparison beside it reads as a finding whatever the step is
+ * called.
+ */
+function reportCadence(
+  reports: readonly FileReport[],
+  checkpoints: Checkpoints,
+): void {
+  logStep('Cadence')
+  logInfo(
+    `Paragraphs of ${checkpoints.cadence} sentences or more measure the words between their longest and shortest sentence, and the times one word opens a sentence.`,
+  )
+  logInfo(
+    `A spread of ${checkpoints.spread} words or under reads as one cadence, and a word opening more than ${checkpoints.opener} sentences is a pattern rather than a coincidence.`,
+  )
+  logInfo(
+    'Both numbers are stated under Rhythm in the write-human skill, which writes them about prose a person reads.',
+  )
+  logInfo(
+    'A shorter paragraph stays unmeasured, since a two-sentence note carries no spread worth reading.',
+  )
+  logInfo(
+    'A healthy range differs by surface, so neither number gates and neither names a file wrong. Terse reference prose sits below the range a page written for a reader sits in.',
+  )
+  logInfo(
+    `The corpus these numbers were read against measured ${BASELINE.flatShare} percent flat overall, and its files carrying ${BASELINE.floor} or more measured paragraphs ran from ${BASELINE.low} to ${BASELINE.high} percent with a median near ${BASELINE.median}. Compare a rate against that rather than against zero.`,
+  )
+
+  const measured = reports.reduce(
+    (sum, report) => sum + report.structure.cadence.measured,
+    0,
+  )
+
+  if (measured === 0) {
+    logInfo(
+      `No paragraph reached ${checkpoints.cadence} sentences, so nothing was measured.`,
+    )
+    return
+  }
+
+  const flat = reports.reduce(
+    (sum, report) => sum + report.structure.cadence.flat,
+    0,
+  )
+  const repeating = reports.reduce(
+    (sum, report) => sum + report.structure.cadence.repeating,
+    0,
+  )
+
+  logInfo(
+    `${plural(measured, 'paragraph')} measured, ${flat} at or under the spread checkpoint (${Math.round((flat / measured) * 100)} percent) and ${repeating} past the opener checkpoint.`,
+  )
+
+  const carrying = reports
+    .filter(
+      (report) =>
+        report.structure.cadence.flattest ||
+        report.structure.cadence.mostRepeated,
+    )
+    .sort(
+      (a, b) =>
+        b.structure.cadence.flat +
+        b.structure.cadence.repeating -
+        (a.structure.cadence.flat + a.structure.cadence.repeating),
+    )
+
+  if (carrying.length === 0) return
+
+  pipeOutput(
+    carrying
+      .map((report) => {
+        const { flattest, mostRepeated } = report.structure.cadence
+        const lines = [
+          flattest &&
+            `  :${flattest.line}  ${plural(flattest.sentences, 'sentence')}, spread ${plural(flattest.spread, 'word')}`,
+          mostRepeated &&
+            `  :${mostRepeated.line}  ${plural(mostRepeated.sentences, 'sentence')}, "${mostRepeated.opener}" opens ${mostRepeated.repeats}`,
+        ].filter(Boolean)
+
+        return `${report.rel}\n${lines.join('\n')}`
+      })
+      .join('\n'),
+  )
+}
+
 /**
  * Names the render width and the blank-line convention on every run.
  *

package/src/markdown/structure.ts

@@ -33,6 +33,14 @@ const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
  * degraded a number and the report had to carry a legend saying which one. The
  * standard still states every number for a reader, and moving one is an edit to
  * both.
+ *
+ * The last three come from the `## Rhythm` section of the `write-human` skill
+ * rather than from a standard. That skill states what good rhythm is and this
+ * measures against the statement, so the numbers are read off the sentences
+ * that already carry them: a longest and shortest sentence within roughly five
+ * words of each other is one cadence, an opening word repeating twice is
+ * coincidence and three times is a pattern, and both rules are written about a
+ * paragraph, which needs a third sentence before either says anything.
  */
 export const CHECKPOINTS = {
   run: 40,
@@ -41,6 +49,37 @@ export const CHECKPOINTS = {
   paragraph: 700,
   sentences: 4,
   renderWidth: 80,
+  cadence: 3,
+  spread: 5,
+  opener: 2,
+} as const
+
+/**
+ * The reading a cadence rate is compared against, rather than a checkpoint.
+ *
+ * A count with nothing beside it reads as a finding, and the two counts the
+ * cadence step reports have no range a reader can place them in: twelve flat
+ * paragraphs out of forty says the same as two without one. Naming that a
+ * healthy range differs by surface states that a range exists rather than what
+ * it looks like, so the reading travels with the command.
+ *
+ * This is an observation rather than a rule, which is why it sits apart from
+ * `CHECKPOINTS`. Nothing compares a run against it and no exit code reads it. A
+ * project whose corpus is entirely terse reference prose is expected to sit
+ * above the high end, and that is the measure working.
+ *
+ * Read across 483 markdown files at `6c273324` on 2026-08-20. A number here
+ * goes stale against the corpus it describes with nothing comparing the two, so
+ * re-measure before moving one.
+ */
+export const BASELINE = {
+  /** Share of every measured paragraph sitting at or under the spread checkpoint. */
+  flatShare: 8,
+  /** Measured paragraphs a file needs before its own rate means anything. */
+  floor: 10,
+  low: 0,
+  median: 6,
+  high: 21,
 } as const
 
 /**
@@ -58,6 +97,12 @@ export interface Checkpoints {
   readonly paragraph: number
   readonly sentences: number
   readonly renderWidth: number
+  /** Sentences a paragraph needs before its cadence is measured at all. */
+  readonly cadence: number
+  /** Words between the longest and shortest sentence, at or under which the paragraph reads as one cadence. */
+  readonly spread: number
+  /** Times one opening word may open a sentence in a paragraph before it is a pattern. */
+  readonly opener: number
 }
 
 export interface BulletFinding {
@@ -72,6 +117,47 @@ export interface ParagraphFinding {
   readonly characters: number
 }
 
+/**
+ * One measured paragraph, carrying both cadence numbers rather than one.
+ *
+ * A paragraph reported for a narrow spread is usually worth reading for its
+ * openers too, and splitting the two into separate finding types would name the
+ * same line twice with half the picture on each.
+ */
+export interface CadenceFinding {
+  readonly line: number
+  readonly sentences: number
+  /** Words between the longest and shortest sentence. */
+  readonly spread: number
+  /** Times the most repeated opening word opens a sentence here. */
+  readonly repeats: number
+  /** The opening word behind `repeats`, lowercased and stripped of punctuation. */
+  readonly opener: string
+}
+
+/**
+ * A file's cadence distribution, reported rather than listed finding by finding.
+ *
+ * Both numbers are advisory in a way even the weight checkpoints are not. A
+ * healthy range differs by surface, so terse reference prose and a page written
+ * for a reader sit at different spreads and one range applied across the corpus
+ * would report the surfaces that are correct. The counts are what a reader
+ * compares against the stated range, and the two worst paragraphs are where
+ * they open the file.
+ */
+export interface CadenceReport {
+  /** Paragraphs carrying at least the floor sentence count. */
+  readonly measured: number
+  /** Measured paragraphs at or under the spread checkpoint. */
+  readonly flat: number
+  /** Measured paragraphs past the opener checkpoint. */
+  readonly repeating: number
+  /** Narrowest paragraph among the flat ones, or undefined when none is flat. */
+  readonly flattest: CadenceFinding | undefined
+  /** Most repetitive paragraph among the repeating ones, or undefined when none repeats. */
+  readonly mostRepeated: CadenceFinding | undefined
+}
+
 export interface StructureReport {
   readonly rel: string
   /** Rendered lines at the render width, not source lines. */
@@ -80,6 +166,7 @@ export interface StructureReport {
   readonly longestRunLine: number
   readonly heavyBullets: readonly BulletFinding[]
   readonly heavyParagraphs: readonly ParagraphFinding[]
+  readonly cadence: CadenceReport
 }
 
 /**
@@ -275,48 +362,46 @@ export function heavyBullets(
   return findings
 }
 
+/**
+ * Splits a paragraph into the sentences terminal punctuation closes.
+ *
+ * A trailing span no punctuation closes is dropped rather than returned, which
+ * keeps this and the count below one definition. The pattern already matches a
+ * paragraph's final period through its end-of-text alternative, so the only
+ * span this drops is a paragraph genuinely ending without terminal punctuation,
+ * which is a fragment rather than a sentence to either measure.
+ */
+function splitSentences(text: string): string[] {
+  const sentences: string[] = []
+  let start = 0
+
+  for (const match of text.matchAll(SENTENCE_END)) {
+    const end = match.index + match[0].length
+    sentences.push(text.slice(start, end).trim())
+    start = end
+  }
+
+  return sentences
+}
+
 function countSentences(text: string): number {
-  return [...text.matchAll(SENTENCE_END)].length
+  return splitSentences(text).length
 }
 
 /**
- * Finds the prose paragraphs past either half of the standard's checkpoint.
+ * Splits the body into its prose paragraphs, each a run of consecutive lines.
  *
- * Both halves are stated in the standard and both are read from it. The weight
- * half was added there rather than borrowed from the bullet checkpoint, which
- * governs a different construct: one number feeding both would move the
- * paragraph rule whenever the bullet rule was changed, and an author reading
- * the sentence cap would find no weight rule to read at all.
- *
- * The two numbers coincide today because paragraph and bullet weight measure
- * one population, sharing a median near 170 characters with no gap behind
- * either candidate. They are separate checkpoints regardless, so either moves
- * without dragging the other.
- *
- * A paragraph is a run of consecutive prose lines. A heading, a list item, a
- * table row, a blockquote, a blank line, and a fence each end one, so a bullet
- * is measured by `heavyBullets` alone and never twice.
+ * A heading, a list item, a table row, a blockquote, a blank line, and a fence
+ * each end one, so a bullet is measured by `heavyBullets` alone and never
+ * twice. Both paragraph measures walk this rather than one each, since two
+ * walks deciding what a paragraph is would drift apart.
  */
-export function heavyParagraphs(
-  lines: readonly BodyLine[],
-  checkpoints: Checkpoints,
-): ParagraphFinding[] {
-  const findings: ParagraphFinding[] = []
+function paragraphBlocks(lines: readonly BodyLine[]): BodyLine[][] {
+  const blocks: BodyLine[][] = []
   let block: BodyLine[] = []
 
   const close = (): void => {
-    if (block.length > 0) {
-      const text = block.map((line) => line.text.trim()).join(' ')
-      const sentences = countSentences(text)
-      const characters = visibleText(text).length
-
-      if (
-        sentences > checkpoints.sentences ||
-        characters > checkpoints.paragraph
-      ) {
-        findings.push({ line: block[0].number, sentences, characters })
-      }
-    }
+    if (block.length > 0) blocks.push(block)
     block = []
   }
 
@@ -340,9 +425,168 @@ export function heavyParagraphs(
 
   close()
 
+  return blocks
+}
+
+/** Folds a paragraph's source lines into the one line they would have wrapped from. */
+function paragraphText(block: readonly BodyLine[]): string {
+  return block.map((line) => line.text.trim()).join(' ')
+}
+
+/**
+ * Finds the prose paragraphs past either half of the standard's checkpoint.
+ *
+ * Both halves are stated in the standard and both are read from it. The weight
+ * half was added there rather than borrowed from the bullet checkpoint, which
+ * governs a different construct: one number feeding both would move the
+ * paragraph rule whenever the bullet rule was changed, and an author reading
+ * the sentence cap would find no weight rule to read at all.
+ *
+ * The two numbers coincide today because paragraph and bullet weight measure
+ * one population, sharing a median near 170 characters with no gap behind
+ * either candidate. They are separate checkpoints regardless, so either moves
+ * without dragging the other.
+ */
+export function heavyParagraphs(
+  lines: readonly BodyLine[],
+  checkpoints: Checkpoints,
+): ParagraphFinding[] {
+  const findings: ParagraphFinding[] = []
+
+  for (const block of paragraphBlocks(lines)) {
+    const text = paragraphText(block)
+    const sentences = countSentences(text)
+    const characters = visibleText(text).length
+
+    if (
+      sentences > checkpoints.sentences ||
+      characters > checkpoints.paragraph
+    ) {
+      findings.push({ line: block[0].number, sentences, characters })
+    }
+  }
+
   return findings
 }
 
+/** Punctuation either side of a word, so an opener is compared on its letters. */
+const WORD_EDGE = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu
+
+/**
+ * The word a sentence opens on, lowercased and stripped of punctuation.
+ *
+ * A sentence opening on a code span yields the command inside it rather than a
+ * backtick, which is the word a reader hears. Casing is dropped because an
+ * opener repeating is a repetition whether or not one of the two sits mid-list
+ * and lost its capital.
+ */
+function openingWord(sentence: string): string {
+  const [first = ''] = sentence.split(/\s+/)
+  return first.replace(WORD_EDGE, '').toLowerCase()
+}
+
+/**
+ * Measures one paragraph's spread and its most repeated opener.
+ *
+ * Words are counted off the text a reader is shown, so a link contributes its
+ * anchor text and a destination contributes nothing. The sentence boundaries do
+ * not move with that masking, since the pattern requires whitespace after the
+ * terminal punctuation and no destination or autolink carries any.
+ */
+function measureParagraph(block: readonly BodyLine[]): CadenceFinding {
+  const sentences = splitSentences(visibleText(paragraphText(block)))
+  const lengths = sentences.map(
+    (sentence) => sentence.split(/\s+/).filter(Boolean).length,
+  )
+
+  const counts = new Map<string, number>()
+  for (const sentence of sentences) {
+    const word = openingWord(sentence)
+    if (word !== '') counts.set(word, (counts.get(word) ?? 0) + 1)
+  }
+
+  let opener = ''
+  let repeats = 0
+  for (const [word, count] of counts) {
+    if (count > repeats) {
+      opener = word
+      repeats = count
+    }
+  }
+
+  // A paragraph closing no sentence at all has no spread rather than a
+  // negative one, and the floor drops it before either number is read.
+  const spread =
+    lengths.length === 0 ? 0 : Math.max(...lengths) - Math.min(...lengths)
+
+  return {
+    line: block[0].number,
+    sentences: sentences.length,
+    spread,
+    repeats,
+    opener,
+  }
+}
+
+/**
+ * Reports how a file's prose is distributed across sentence length and opening
+ * word, which is the layer the ban sets cannot reach.
+ *
+ * A banned-word list expresses negatives and every symptom this answers is the
+ * 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.
+ *
+ * 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
+ * written about a third sentence turning a coincidence into a pattern, so
+ * neither measure says anything before the floor is reached.
+ */
+export function measureCadence(
+  lines: readonly BodyLine[],
+  checkpoints: Checkpoints,
+): CadenceReport {
+  const measured = paragraphBlocks(lines)
+    .map(measureParagraph)
+    .filter((finding) => finding.sentences >= checkpoints.cadence)
+
+  const flat = measured.filter(
+    (finding) => finding.spread <= checkpoints.spread,
+  )
+  const repeating = measured.filter(
+    (finding) => finding.repeats > checkpoints.opener,
+  )
+
+  return {
+    measured: measured.length,
+    flat: flat.length,
+    repeating: repeating.length,
+    flattest: worst(flat, (finding) => -finding.spread),
+    mostRepeated: worst(repeating, (finding) => finding.repeats),
+  }
+}
+
+/**
+ * The file's worst paragraph on one measure, earliest line breaking a tie.
+ *
+ * Only paragraphs already past their checkpoint are passed in, so a file
+ * reading healthy names nothing rather than naming its least healthy paragraph,
+ * which a reader would take for a finding.
+ */
+function worst(
+  findings: readonly CadenceFinding[],
+  rank: (finding: CadenceFinding) => number,
+): CadenceFinding | undefined {
+  return findings.reduce<CadenceFinding | undefined>(
+    (held, finding) => (!held || rank(finding) > rank(held) ? finding : held),
+    undefined,
+  )
+}
+
 export function measureStructure(
   rel: string,
   lines: readonly BodyLine[],
@@ -356,5 +600,6 @@ export function measureStructure(
     longestRunLine: run.line,
     heavyBullets: heavyBullets(lines, checkpoints),
     heavyParagraphs: heavyParagraphs(lines, checkpoints),
+    cadence: measureCadence(lines, checkpoints),
   }
 }

package/standards/session.md

@@ -57,7 +57,7 @@ Add a section only for content that fits none of the three and would otherwise b
 ## Writing one
 
 1. Capture what the session learned first, so the map cites what was written instead of restating the same lesson in prose.
-2. Run `aitk claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`. A skill body enters a session once and re-invoking the skill replays the held copy rather than the file, so the drift is worst at exactly this moment and a name here is a body the session has been following out of date. This step belongs to session length rather than to any role, so every writer runs it, and a refusal names the boundary of what the verb can read rather than a fault.
+2. Run `aitk claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`. A skill body enters a session once and re-invoking the skill does not re-read the file, so the drift is worst at exactly this moment and a name here is a body the session has been following out of date. Recording a name is not acting on it, and the verb misses a body this session edited and has not committed. This step belongs to session length rather than to any role, so every writer runs it, and a refusal names the boundary of what the verb can read rather than a fault.
 3. Recover that commit from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. Nothing on the machine records it. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making.
 4. Write only what a compaction destroys and no other artifact already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a measurement folder holds its track.
 5. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.