@erclx/aitk 0.52.0 → 0.53.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.52.0",
+  "version": "0.53.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-design-extract/SKILL.md

@@ -33,6 +33,7 @@ Read these from the project root on both paths, skipping any that do not exist:
 - `CLAUDE.md`: voice, personality, spelling rules
 - `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
 - `.claude/standards/prose.md`: tone constraints
+- `.claude/standards/markdown.md`: punctuation and formatting constraints
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
@@ -54,7 +55,7 @@ Use the returned content as the target shape. Keep every section heading and eve
 
 ## Step 4: fill the template
 
-Walk each section once. Follow `.claude/standards/prose.md` throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
+Walk each section once. Follow `.claude/standards/markdown.md` for punctuation and `.claude/standards/prose.md` for word choice throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
 
 Mark any cell not traced to a source value by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` after the row breaks the parser. A prose section takes its uncertainty inline instead, for example `Proposed 150ms ease-out, not yet confirmed.`, because a trailing tag on a sentence renders raw in the preview.
 

package/claude/skills/claude-docs/SKILL.md

@@ -97,7 +97,7 @@ For each doc with relevant changes, apply updates following these rules. Read a
 
 - Update only the sections affected by session decisions.
 - Do not rewrite sections unrelated to what changed.
-- Follow `.claude/standards/prose.md` for all edits.
+- Follow `.claude/standards/prose.md` and `.claude/standards/markdown.md` for all edits.
 
 Write each updated file immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 

package/claude/skills/claude-memory-capture/SKILL.md

@@ -23,7 +23,8 @@ Read in parallel from the project root, skipping any that do not exist:
 - `CLAUDE.md`: Memory section rules, including save thresholds and file format overrides
 - `.claude/memory/index.md`: existing index, to avoid duplicates
 - `.claude/context/index.md`: the domain catalog Step 3 routes against
-- `.claude/standards/prose.md`: prose conventions applied to memory file bodies
+- `.claude/standards/prose.md`: voice and banned words applied to memory file bodies
+- `.claude/standards/markdown.md`: punctuation and formatting applied to memory file bodies
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/claude-standards-audit/SKILL.md

@@ -9,6 +9,7 @@ description: Audits changed markdown files against every authoring standard that
 
 - Resolve the base ref first, per Diff baseline below, then scope the file list exactly as Step 1 does, fallback included. If no markdown files changed, stop: `✅ No markdown changes to audit.` A guard that reads bare local `main`, or that skips the unusable-baseline fallback, passes the skill clean on a branch it never read.
 - If neither `.claude/standards/prose.md` nor `${CLAUDE_SKILL_DIR}/../../standards/prose.md` is present, stop: `❌ prose.md standard not found. Install toolkit standards first.` Test the file rather than the directory, since a project that installed standards before a given file existed keeps the directory without ever receiving that file.
+- Apply the same test to `markdown.md`, stopping with its own name. It carries the character bans and the formatting rules, so a run reaching only `prose.md` reports word choice against a clean file and calls the pass complete.
 
 ## Diff baseline
 
@@ -72,7 +73,7 @@ Read each applicable standard once. For each changed file, audit against every r
 - **Pattern rules**: grep the file for every token the standard bans. Grep is authoritative. Reading alone misses occurrences.
 - **Judgment rules**: check each rule in context against the standard that states it.
 
-Every changed markdown file gets the prose pattern pass, since `.claude/standards/prose.md` applies to all of them. Take the banned tokens from that standard at read time rather than from a list held here.
+Every changed markdown file gets the prose pattern pass, since `.claude/standards/prose.md` and `.claude/standards/markdown.md` both apply to all of them. Take the banned tokens from those standards at read time rather than from a list held here. The banned words sit in the first and the banned characters in the second, so a pass reading one file finds half the tokens.
 
 ## Step 4: report
 
@@ -81,8 +82,9 @@ Group findings by file with line references, naming the standard each one comes
 ```markdown
 path/to/file.md
 
-- L12: `prose.md`, em dash in prose
-- L34: `prose.md`, semicolon used to join clauses
+- L12: `markdown.md`, em dash in prose
+- L34: `markdown.md`, semicolon used to join clauses
+- L51: `prose.md`, vague qualifier `simply`
 - L67: `context.md`, decision entry names no rejected alternative
 ```
 

package/claude/skills/create-skill/SKILL.md

@@ -9,7 +9,8 @@ disable-model-invocation: true
 Read these files from the project root in parallel:
 
 - `.claude/standards/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
-- `.claude/standards/prose.md`: prose conventions for skill body text
+- `.claude/standards/prose.md`: voice and banned words for skill body text
+- `.claude/standards/markdown.md`: punctuation and formatting for skill body text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/create-snippet/SKILL.md

@@ -7,10 +7,11 @@ description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. U
 
 Creates one snippet file. Read these files in parallel:
 
-- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
+- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
 - `${CLAUDE_SKILL_DIR}/references/snippets.md`: authoring conventions, invocation channels, use patterns
 
-Read `${CLAUDE_SKILL_DIR}/../../standards/prose.md` instead when the project does not have it.
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
 ## Guards
 

package/claude/skills/create-snippet/references/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/claude/skills/create-standard/SKILL.md

@@ -7,7 +7,8 @@ description: Creates a new standard file in `standards/` or `.claude/standards/`
 
 Creates one standard file. Read these files in parallel:
 
-- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
+- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
 - `.claude/standards/standard.md` from the project root: the meta-standard for shape, frontmatter, and structure
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/docs-sync/SKILL.md

@@ -7,7 +7,8 @@ description: Rewrites stale `README.md` and `docs/*.md` sections based on change
 
 Read these files from the project root in parallel:
 
-- `.claude/standards/prose.md`: prose conventions for all generated text
+- `.claude/standards/prose.md`: voice and banned words for all generated text
+- `.claude/standards/markdown.md`: punctuation and formatting for all generated text
 - `.claude/standards/readme.md`: README structure, required sections, and content rules
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/git-issue/SKILL.md

@@ -12,7 +12,8 @@ Format an issue from session context following the issue standard, then file it
 Read these in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/issue.md`: issue title, labels, body sections, and banned phrases
-- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
+- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/git-issue/references/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/claude/skills/git-pr/SKILL.md

@@ -11,7 +11,8 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/branch.md`: branch format, valid types, and constraints
 - `${CLAUDE_SKILL_DIR}/references/pr.md`: structure, rules, and banned phrases
-- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
+- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
 - `.claude/standards/versioning.md` from the project root: phase label vs semver discipline
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/git-pr/references/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/claude/skills/git-split/references/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/claude/skills/git-stage/SKILL.md

@@ -8,7 +8,8 @@ description: Groups staged files by concern and generates one conventional commi
 Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/commit.md`: format, types, scopes, and constraints
-- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
+- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

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

@@ -1,5 +1,5 @@
 ---
-description: Route markdown edits to the prose standard for voice, structure, formatting, and punctuation
+description: Route markdown edits to the prose standard for voice, language, and frontmatter wording
 paths:
   - '**/*.md'
 ---
@@ -8,5 +8,6 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/prose.md` for all prose: voice, structure, formatting, language, and banned punctuation. It is the single source.
-- Read it before a substantial prose edit. Do not work the bans from memory.
+- Follow `.claude/standards/prose.md` for voice, language, and the wording of a `title` or `description`. It is the single source.
+- Read it before a substantial prose edit. Do not work the banned words from memory.
+- Punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.

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

@@ -0,0 +1,13 @@
+---
+description: Route markdown edits to the markdown standard for headings, lists, punctuation, and file references
+paths:
+  - '**/*.md'
+---
+
+# Markdown mechanics standards
+
+## Authority
+
+- Follow `.claude/standards/markdown.md` for headings, paragraph and list structure, code spans, punctuation, emphasis, and file references. It is the single source.
+- Read it before a substantial markdown edit. Do not work the banned characters from memory.
+- Voice, language, and frontmatter wording are a separate topic. `500-prose` routes them.

package/governance/stacks/base.toml

@@ -1,2 +1,2 @@
 extends = ""
-rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]
+rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "501-markdown", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]

package/package.json

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

package/scripts/core/install-check.sh

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

package/src/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/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.
 

package/standards/readme.md

@@ -5,7 +5,7 @@ description: Readme voice, structure, and content conventions
 
 # Readme reference
 
-Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so `prose.md` yields to it there. The yield covers voice alone. The punctuation bans, spelling rules, banned words, and formatting rules in `prose.md` stay in force, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so `prose.md` yields to it there. The yield covers voice alone. The spelling rules and banned words in `prose.md` stay in force, as do the punctuation and formatting rules in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
@@ -15,7 +15,8 @@ Governs every `README.md`: voice, heading structure, required and optional secti
 
 Does not govern:
 
-- Punctuation, formatting, spelling, and banned words in README prose: `prose.md`, which yields the voice and keeps the rest
+- Spelling and banned words in README prose: `prose.md`, which yields the voice and keeps the rest
+- Punctuation and formatting in README prose: `markdown.md`, which yields nothing
 - Product scope and goals: `requirements.md`
 
 ## Voice

package/standards/skill.md

@@ -17,7 +17,8 @@ Does not govern:
 
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
 - Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
-- Voice, punctuation, and formatting in a skill body: `prose.md`
+- Voice and word choice in a skill body: `prose.md`
+- Punctuation and formatting in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
 - The domain conventions a skill cites, each of which belongs to the standard that owns it
 

package/standards/standard.md

@@ -17,7 +17,8 @@ Governs each authored standard under `standards/`: its stated jurisdiction, succ
 
 Does not govern:
 
-- The voice, punctuation, and formatting a standard is written in: `prose.md`
+- The voice and word choice a standard is written in: `prose.md`
+- The punctuation and formatting a standard is written in: `markdown.md`
 - The shape of any artifact a standard governs, which is that standard's own subject
 
 ## What a working standard looks like

package/standards/versioning.md

@@ -16,7 +16,8 @@ Does not govern:
 - The format of a phase label, which is project-specific by the rule below
 - Task filenames and board layout: `tasks.md`
 - Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
-- Voice, punctuation, and formatting in any text carrying a label: `prose.md`
+- Voice and word choice in any text carrying a label: `prose.md`
+- Punctuation and formatting in any text carrying a label: `markdown.md`
 
 ## Phase labels
 

package/standards/wireframes.md

@@ -17,7 +17,8 @@ Does not govern:
 
 - Tokens, typography, spacing, and the rest of the visual system: `design.md`
 - The mechanism behind a surface: `context.md`
-- Voice, punctuation, and formatting in wireframe prose: `prose.md`
+- Voice and word choice in wireframe prose: `prose.md`
+- Punctuation and formatting in wireframe prose: `markdown.md`
 
 ## What a working wireframe looks like
 
@@ -74,7 +75,7 @@ Reference the context entry from the wireframe by path when a reader needs the m
 ## Maintenance
 
 - When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
-- The Behavior and Copy prose around an ASCII block is prose and follows `prose.md`. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
+- The Behavior and Copy prose around an ASCII block is prose and follows `prose.md` and `markdown.md`. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
 
 ## Template
 

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -19,6 +19,10 @@ esac
 # Read the closed-set word bans from the standard so the hook never carries a
 # second copy. Every "Do not use ... (`a`, `b`)" bullet contributes its
 # single-word backticked terms, which skips the multi-word and punctuation bans.
+#
+# The word bans sit in prose.md and the em-dash and semicolon bans in
+# markdown.md, so this parses the first and hardcodes the second. A "Do not use"
+# bullet added to markdown.md is parsed by nothing and enforces silently.
 standard="${CLAUDE_PROJECT_DIR:-.}/.claude/standards/prose.md"
 words=""
 if [ -f "$standard" ]; then
@@ -56,6 +60,6 @@ hits=$(awk -v words="$words" '
 
 [ -z "$hits" ] && exit 0
 
-msg=$(printf 'Standards-audit: prose.md violations in %s. Rewrite or restructure (do not lazy-swap).\n%s' "$file" "$hits")
+msg=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite or restructure (do not lazy-swap).\n%s' "$file" "$hits")
 
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'