@erclx/aitk 0.51.0 → 0.53.0

package/src/claude/seeds.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs'
-import { chmod } from 'node:fs/promises'
-import { join } from 'node:path'
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 import { copyPreservingMode } from '@/copy'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 
 const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
@@ -122,12 +123,25 @@ export function countByScope(seeds: readonly Seed[]): SeedCounts {
 /**
  * Copies each pending seed. Hooks get the executable bit the way `chmod +x`
  * granted it, added on top of whatever mode the destination already carried.
+ *
+ * A markdown seed is rewritten rather than copied, so the stub marker the seed
+ * gate reads does not reach the target. Every other seed copies byte for byte,
+ * which is what keeps the hook scripts and `settings.json` untouched.
  */
 export async function applySeeds(seeds: readonly Seed[]): Promise<string[]> {
   const applied: string[] = []
 
   for (const seed of seeds) {
-    await copyPreservingMode(seed.src, seed.dest)
+    if (rewritesOnInstall(seed.src)) {
+      await mkdir(dirname(seed.dest), { recursive: true })
+      await writeFile(
+        seed.dest,
+        stripSeedMarker(await readFile(seed.src, 'utf8')),
+      )
+    } else {
+      await copyPreservingMode(seed.src, seed.dest)
+    }
+
     if (seed.executable) await chmod(seed.dest, 0o755)
     applied.push(seed.applyLabel)
   }

package/src/commands/context.ts

@@ -21,6 +21,7 @@ import {
   presentNames,
   resolveFolders,
 } from '@/context/folders'
+import { isGating } from '@/context/gate'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
 import {
   frameError,
@@ -34,8 +35,8 @@ import {
   plural,
 } from '@/ui'
 
-/** Returned when an unresolved citation is found, which is the gating check. */
-const EXIT_UNRESOLVED = 2
+/** Returned when a gating finding is present. */
+const EXIT_GATE = 2
 
 /** A name of dots alone is `.` or `..`, both of which escape the audit root. */
 const FOLDER_NAME = /^(?!\.+$)[A-Za-z0-9._-]+$/
@@ -44,6 +45,7 @@ interface AuditCommandOptions {
   readonly json?: boolean
   readonly folder?: string
   readonly citationsOnly?: boolean
+  readonly gate?: boolean
 }
 
 export function register(program: Command): void {
@@ -65,17 +67,23 @@ export function register(program: Command): void {
       'Comma-separated folder names, resolved under .claude/ then the project root',
     )
     .option('--citations-only', 'Run the gating citation check alone')
+    .option(
+      '--gate',
+      'Also fail on a missing required section or index drift, the findings that are facts',
+    )
     .addHelpText(
       'after',
       [
         '',
         'Exit codes:',
-        '  0  the audit completed with every cited path resolving',
+        '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
-        '  2  a cited path did not resolve',
+        '  2  a gating finding is present',
         '',
-        'Only unresolved citations set a failing exit code. Section, length,',
-        'depth, bullet, table, provenance, and index findings are advisory.',
+        'An unresolved citation always gates. --gate widens the gate to the',
+        'other two findings that are facts rather than judgments: a missing',
+        'required section and index drift. Length, depth, bullet, table, and',
+        'provenance findings are thresholds and stay advisory under both.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -83,6 +91,7 @@ export function register(program: Command): void {
         '  aitk context audit --citations-only',
         '  aitk context audit --folder context,diagrams',
         '  aitk context audit --folder docs',
+        '  aitk context audit tooling/base/seeds --gate',
         '',
       ].join('\n'),
     )
@@ -118,6 +127,17 @@ async function runAudit(
   const root = resolve(path ?? process.cwd())
   const names = parseFolders(opts.folder)
   const gateOnly = opts.citationsOnly ?? false
+  const widened = opts.gate ?? false
+
+  // `--citations-only` runs the citation check alone, so the two findings
+  // `--gate` adds are never measured. Honouring both would exit 0 on a seed
+  // short a required section, which is the pass a gate exists to prevent.
+  if (gateOnly && widened) {
+    return refuse(
+      '--citations-only runs the citation check alone, so --gate would widen the gate to findings the run never measures. Pass one.',
+      gateOnly,
+    )
+  }
 
   if (typeof names === 'string') return refuse(names, gateOnly)
 
@@ -213,7 +233,14 @@ async function runAudit(
     )
   }
 
-  return citations.unresolved.length > 0 ? EXIT_UNRESOLVED : 0
+  const gating = isGating({
+    unresolvedCitations: citations.unresolved.length,
+    sections,
+    drift,
+    widened,
+  })
+
+  return gating ? EXIT_GATE : 0
 }
 
 function refuse(message: string, gateOnly: boolean): number {

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 bans out of `prose.md`.
+ * `.claude/hooks/standards-audit.sh` reads its word bans out of `prose.md`.
  */
 export async function loadVocabulary(root: string): Promise<Vocabulary> {
   for (const ruleRoot of RULE_ROOTS) {

package/src/context/audit.ts

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 import type { AuditedFolder } from '@/context/folders'
+import { isStubSeed } from '@/seed-marker'
 
 /** Checkpoints quoted from `standards/context.md`. Neither is a cap. */
 export const LENGTH_CHECKPOINT = 150
@@ -166,6 +167,12 @@ export interface EntryReport {
    * is `missingSections`, since one entry answers for its siblings.
    */
   readonly sections: readonly string[]
+  /**
+   * Whether the file declares itself a skeleton, which excludes it from the
+   * section check alone. Every other measure still reads it, since a stub is
+   * exempt from owing sections rather than from being well formed.
+   */
+  readonly stub: boolean
 }
 
 export interface SectionFinding {
@@ -544,6 +551,7 @@ export function measureEntry(
     provenance: governsContent ? provenance(lines) : [],
     heavyBullets: governsContent ? heavyBullets(lines) : [],
     sections: governsContent ? declaredSections(lines) : [],
+    stub: isStubSeed(source),
   }
 }
 
@@ -615,9 +623,15 @@ export function missingSections(
   for (const folder of folders) {
     if (!governsContent(folder) || folder.entries.length === 0) continue
 
+    // A stub owes no sections, so it is dropped before either branch rather
+    // than inside them. Leaving one in the split-folder aggregate would let a
+    // skeleton answer for the siblings that do owe the sections.
     const reports = folder.entries
       .map((path) => byRel.get(relative(root, path)))
       .filter((entry) => entry !== undefined)
+      .filter((entry) => !entry.stub)
+
+    if (reports.length === 0) continue
 
     if (folder.nested) {
       const missing = shortOf(reports.flatMap((entry) => entry.sections))

package/src/context/gate.ts

@@ -0,0 +1,43 @@
+import type { SectionFinding } from '@/context/audit'
+import type { FolderDrift } from '@/context/index-drift'
+
+export interface GateInput {
+  /** Cited paths that resolved to nothing, which gate under either mode. */
+  readonly unresolvedCitations: number
+  readonly sections: readonly SectionFinding[]
+  readonly drift: readonly FolderDrift[]
+  /**
+   * Whether the caller asked for the widened gate. False leaves a missing
+   * section and a drifted index advisory, which is what the project-root stage
+   * runs so a judgment threshold never fails a push.
+   */
+  readonly widened: boolean
+}
+
+/** Whether any folder disagrees with its own index. */
+export function hasDrift(drift: readonly FolderDrift[]): boolean {
+  return drift.some(
+    (folder) => folder.unlisted.length > 0 || folder.missing.length > 0,
+  )
+}
+
+/**
+ * Whether the audit found something that should fail the caller.
+ *
+ * An unresolved citation is a broken pointer and gates unconditionally. The two
+ * findings `--gate` adds are the ones answerable from the file itself: a
+ * required section it does not declare, and an index disagreeing with its
+ * folder. Length, depth, bullet, table, and provenance findings are thresholds
+ * a reader weighs, so they stay out under both modes.
+ */
+export function isGating({
+  unresolvedCitations,
+  sections,
+  drift,
+  widened,
+}: GateInput): boolean {
+  if (unresolvedCitations > 0) return true
+  if (!widened) return false
+
+  return sections.length > 0 || hasDrift(drift)
+}

package/src/seed-marker.ts

@@ -0,0 +1,74 @@
+/**
+ * The frontmatter field exempting a seed from the section check the seed gate
+ * runs.
+ *
+ * The check has a false-positive class its own comment records: a standard may
+ * sanction omitting a section, and no measure separates that from a file that
+ * forgot it. Reporting is the right response in a live project, where the
+ * finding is advisory. The seed gate promotes the same finding to a failing
+ * exit code, so the seed tree needs a way to say the omission is deliberate.
+ */
+export const SEED_STUB_FIELD = 'stub'
+
+/**
+ * Whether an install rewrites this seed rather than copying it byte for byte.
+ *
+ * This answers what the caller branches on and not whether the file holds a
+ * marker, which is `isStubSeed` reading content. Only markdown carries
+ * frontmatter, so only markdown can hold one, and the extension decides the
+ * copy path without opening the file. Every install path and the drift report
+ * ask this one question, or the report compares a marked source against a
+ * stripped target and reads a seed nobody touched as drifted.
+ */
+export function rewritesOnInstall(src: string): boolean {
+  return src.endsWith('.md')
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---(\n|$)/
+const STUB_LINE = new RegExp(`^${SEED_STUB_FIELD}:[ \\t]*true[ \\t]*$`, 'm')
+
+/**
+ * Whether the source declares itself a skeleton for the target to fill.
+ *
+ * Only `true` counts. A field set to anything else reads as a seed that meant
+ * to turn the exemption off, and treating an unparsed value as exempt would
+ * make a typo silence the gate.
+ */
+export function isStubSeed(source: string): boolean {
+  const block = source.match(FRONTMATTER)
+  if (!block) return false
+
+  return STUB_LINE.test(block[1])
+}
+
+/**
+ * Removes the marker so it reaches no target.
+ *
+ * The field is toolkit bookkeeping about the seed tree, and a project that
+ * received it would carry a field its own tooling never reads. A file whose
+ * frontmatter holds nothing else loses the block entirely rather than keeping
+ * an empty one.
+ */
+export function stripSeedMarker(source: string): string {
+  const block = source.match(FRONTMATTER)
+  if (!block) return source
+
+  const kept = block[1]
+    .split('\n')
+    .filter((line) => !STUB_LINE.test(line))
+    .join('\n')
+
+  // A function replacement, because a string one reads `$1` and `$&` in the
+  // kept fields as references to this match. A `description` naming a dollar
+  // amount would otherwise substitute the whole frontmatter into itself and
+  // carry the marker along with it.
+  if (kept.trim() !== '') {
+    const replacement = `---\n${kept}\n---${block[2] ?? ''}`
+    return source.replace(FRONTMATTER, () => replacement)
+  }
+
+  // Dropping the block takes the blank line that separated it from the body
+  // with it. Leaving that behind opens the installed file on whitespace, which
+  // is a diff every target would carry against its own formatter.
+  return source.slice(block[0].length).replace(/^\n+/, '')
+}

package/src/sync/seeds-report.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { relative } from 'node:path'
 import { planSeeds, type Seed } from '@/claude/seeds'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 
 /**
@@ -106,6 +107,20 @@ function attribute(
   return false
 }
 
+/**
+ * Compares the target against what an install would write, not against the seed
+ * source. The two differ for a markdown seed carrying the stub marker, which the
+ * install strips, so comparing sources would report a file the target never
+ * touched as drifted for as long as the marker stays set.
+ */
 function sameContent(source: string, dest: string): boolean {
-  return readFileSync(source).equals(readFileSync(dest))
+  const installed = readFileSync(dest)
+
+  if (!rewritesOnInstall(source)) {
+    return readFileSync(source).equals(installed)
+  }
+
+  return (
+    stripSeedMarker(readFileSync(source, 'utf8')) === installed.toString('utf8')
+  )
 }

package/src/tooling/inject.ts

@@ -10,6 +10,7 @@ import {
 import { dirname, join } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
@@ -44,6 +45,21 @@ export async function injectConfigs(
   return applied
 }
 
+/**
+ * Writes a seed to a target that does not have it, dropping the stub marker on
+ * the way. The marker is toolkit bookkeeping read by the seed gate, so a target
+ * receiving it would carry a field its own tooling never reads. Only markdown
+ * carries frontmatter, and every other seed copies byte for byte.
+ */
+async function writeSeed(src: string, dest: string): Promise<void> {
+  if (!rewritesOnInstall(src)) {
+    await copyFile(src, dest)
+    return
+  }
+
+  await writeFile(dest, stripSeedMarker(await readFile(src, 'utf8')))
+}
+
 /**
  * Copies a seed when the target lacks it. When the target already has one and
  * the seed is a `.txt` word list, missing lines are appended and the file is
@@ -53,7 +69,7 @@ async function mergeSeedFile(src: string, dest: string): Promise<void> {
   await mkdir(dirname(dest), { recursive: true })
 
   if (!existsSync(dest)) {
-    await copyFile(src, dest)
+    await writeSeed(src, dest)
     return
   }
 

package/standards/bundled/issue.md

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

package/standards/bundled/pr.md

@@ -15,7 +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, punctuation, and banned words in pull request prose: `prose.md`
+- Voice and banned words in pull request prose: `prose.md`
+- Punctuation and formatting in pull request prose: `markdown.md`
 
 ## Title
 

package/standards/bundled/snippets.md

@@ -13,7 +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, punctuation, and formatting in snippet prose: `prose.md`
+- Voice and word choice in snippet prose: `prose.md`
+- Punctuation and formatting in snippet prose: `markdown.md`
 
 ## What a snippet is
 

package/standards/diagrams.md

@@ -15,7 +15,8 @@ Governs per-kind diagram entries under `.claude/diagrams/`: which question each
 
 Does not govern:
 
-- Punctuation, formatting, and language in explanation prose and node labels: `prose.md`, whose bans the yield does not lift
+- 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
 - 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`
@@ -93,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. Punctuation, formatting, and language bans stay in force.
+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.
 
 ## Verification
 
@@ -120,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`. 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 `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 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/index.md

@@ -11,7 +11,8 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
-- [Prose reference](prose.md): Voice, structure, formatting, and language rules for reference markdown
+- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+- [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan run against finished text leaving through a channel no automated check covers
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md

package/standards/markdown.md

@@ -0,0 +1,72 @@
+---
+title: Markdown reference
+description: Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+---
+
+# 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.
+
+## Scope
+
+Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, 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 none of their own to shape.
+
+Does not govern:
+
+- Voice, word choice, and the wording of a `title` or `description`: `prose.md`
+- What sections a document has, or what belongs in each: the standard for that document type
+- 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`
+
+## Headings
+
+- H1 for document title, H2 for main sections, H3 for subsections
+- Use sentence case for all headings (H1, H2, H3)
+- Proper nouns and product names retain their casing in headings
+
+## Paragraphs and lists
+
+- Use prose by default. Reserve bullets for discrete, unrelated items.
+- Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
+- Keep bullets tight. If a bullet needs more than a couple of sentences, it belongs in prose.
+- Use dashes (`-`) not asterisks (`*`) for bulleted lists
+- Do not end single-sentence or fragment bullets with a period. Use periods when a bullet has two or more sentences.
+- For key path lists, use colon format: `- \`src/\`: description`. Never use an em dash.
+- Do not introduce a list with a "Here are the X:" or "The following X:" lead-in
+
+## Code and identifiers
+
+- Wrap commands, API names, file paths, and code identifiers in backticks
+- Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
+- In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
+
+## Punctuation
+
+- 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.
+
+## Emphasis and dividers
+
+- Do not over-format with excessive bold, italic, or header usage
+- Do not use horizontal rules or dividers (`---`) in body content. The `---` delimiters of a YAML frontmatter block at the top of the file are allowed.
+
+## Links and file references
+
+- Use descriptive anchor text for links. Avoid `click here` or `read more`.
+- Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed. Never repeat the path verbatim as the label.
+
+## Examples
+
+Each pair shows a banned pattern and its fix.
+
+```markdown
+Bad: See [.claude/context/retrieval.md](.claude/context/retrieval.md) for the retrieval flow.
+Good: See `.claude/context/retrieval.md` for the retrieval flow.
+```
+
+```markdown
+Bad: Read [docs/development.md](docs/development.md) before contributing.
+Good: Read the [development guide](docs/development.md) before contributing.
+```

package/standards/prose.md

@@ -1,18 +1,19 @@
 ---
 title: Prose reference
-description: Voice, structure, formatting, and language rules for reference markdown
+description: Voice, language, and frontmatter wording for reference markdown
 ---
 
 # Prose reference
 
-Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. Punctuation, formatting, and language rules below stay in force on every surface, including the surfaces no automated check reaches.
+Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. The language rules below stay in force on every surface, including the surfaces no automated check reaches, as do the mechanics in `markdown.md`.
 
 ## Scope
 
-Governs voice, punctuation, formatting, and word choice wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and yields on voice alone where that standard states one.
+Governs voice, word choice, and frontmatter wording wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, yields on voice alone where that standard states one, and carries no template because voice is written across every document and has none of its own to shape.
 
 Does not govern:
 
+- Headings, list and paragraph structure, code spans, punctuation, emphasis, and file references: `markdown.md`
 - 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.
 - Phase-label and semver discipline: `versioning.md`
@@ -28,52 +29,8 @@ Does not govern:
 - Use substantive connectives where flow matters, but never add words solely for rhythm. Terse reference prose needs no padding.
 - Be direct on established facts. Hedge on genuinely uncertain claims.
 - Assume developer-level technical knowledge. Skip hand-holding explanations.
-- Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
-
-## Structure
-
-### Headings
-
-- H1 for document title, H2 for main sections, H3 for subsections
-- Use sentence case for all headings (H1, H2, H3)
-- Proper nouns and product names retain their casing in headings
-
-### Paragraphs and lists
-
 - Front-load key information in each paragraph. Keep paragraphs concise and scannable.
 - Every sentence must provide new information. Cut redundant context.
-- Use prose by default. Reserve bullets for discrete, unrelated items.
-- Keep bullets tight. If a bullet needs more than a couple of sentences, it belongs in prose.
-
-## Formatting
-
-### Lists
-
-- Use dashes (`-`) not asterisks (`*`) for bulleted lists
-- Do not end single-sentence or fragment bullets with a period. Use periods when a bullet has two or more sentences.
-- For key path lists, use colon format: `- \`src/\`: description`. Never use an em dash.
-- Do not introduce a list with a "Here are the X:" or "The following X:" lead-in
-
-### Code and identifiers
-
-- Wrap commands, API names, file paths, and code identifiers in backticks
-- Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
-- In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
-
-### Punctuation
-
-- 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.
-
-### Emphasis and dividers
-
-- Do not over-format with excessive bold, italic, or header usage
-- Do not use horizontal rules or dividers (`---`) in body content. The `---` delimiters of a YAML frontmatter block at the top of the file are allowed.
-
-### Links and file references
-
-- Use descriptive anchor text for links. Avoid `click here` or `read more`.
-- Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) for cross-folder navigation. Never repeat the path verbatim as the label.
 
 ## Language
 
@@ -86,6 +43,8 @@ Does not govern:
 - 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.
 
+The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and these are word choice. A surface applying both reads both files.
+
 ## Frontmatter descriptions
 
 When frontmatter carries a short `title` or `description` used for catalog display:
@@ -122,13 +81,3 @@ Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
 Bad: It might be worth considering whether to enable caching.
 Good: Enable caching for read-heavy endpoints. Skip it for writes.
 ```
-
-```markdown
-Bad: See [.claude/context/retrieval.md](.claude/context/retrieval.md) for the retrieval flow.
-Good: See `.claude/context/retrieval.md` for the retrieval flow.
-```
-
-```markdown
-Bad: Read [docs/development.md](docs/development.md) before contributing.
-Good: Read the [development guide](docs/development.md) before contributing.
-```

package/standards/publish.md

@@ -11,7 +11,8 @@ Governs the scan an author runs against finished text on its way out, and the re
 
 Does not govern:
 
-- Which characters are banned, and the voice and formatting the text is written in: `prose.md`
+- Which characters are banned, and the formatting the text carries: `markdown.md`
+- The voice and word choice the text is written in: `prose.md`
 - The phase-label rule and the table of surfaces each namespace may appear on: `versioning.md`
 - Which gap a given surface has, and what it publishes through, which that surface names for itself
 
@@ -23,7 +24,7 @@ Run the scan as an explicit step against the finished text. Having read the unde
 
 ## Banned characters
 
-`prose.md` holds the character bans. Read it at scan time rather than working them from memory, then scan the drafted text and rewrite each occurrence.
+`markdown.md` holds the character bans and `prose.md` holds the banned words. Read both at scan time rather than working them from memory, then scan the drafted text and rewrite each occurrence.
 
 Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.