@erclx/aitk 0.105.0 → 0.107.0

package/standards/memory.md

@@ -18,8 +18,8 @@ Does not govern:
 - The per-domain entry a domain fact is routed to instead of memory: `context.md`
 - The feature plan a session executes, and its answer contract: `plan.md`
 - The task file tracking what is being built: `tasks.md`
-- Voice and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 - Which facts a project captures at all, and where the folder sits, which are project policy
 
 ## What a working entry looks like

package/standards/plan.md

@@ -19,8 +19,8 @@ Does not govern:
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
 - The transform from a branch name to a slug: `slug.md`
-- Voice and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 - When a plan is written at all, and whether a short one goes to a file or to the conversation, which belong to the surface driving it
 
 ## What a working plan looks like

package/standards/publish.md

@@ -12,7 +12,7 @@ Governs the scan an author runs against finished text on its way out, the form a
 Does not govern:
 
 - 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 voice and rhythm the text is written in: the `write-human` skill
 - 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
 
@@ -24,7 +24,7 @@ Run the scan as an explicit step against the finished text. Having read the unde
 
 ## Banned characters
 
-`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.
+`markdown.md` holds the character bans and the banned words alike. Read it at scan time rather than working the sets 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 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.
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the spelling rules, banned words, punctuation, and formatting 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,13 +15,13 @@ Governs every `README.md`: voice, heading structure, required and optional secti
 
 Does not govern:
 
-- 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
+- Rhythm and sentence construction in README prose: the `write-human` skill, which yields the voice and keeps the rest
+- Spelling, banned words, punctuation, and formatting in README prose: `markdown.md`, which yields nothing
 - Product scope and goals: `requirements.md`
 
 ## Voice
 
-Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice in `prose.md`, since its reader has already committed and arrived looking for a fact.
+Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice the `write-human` skill carries, since its reader has already committed and arrived looking for a fact.
 
 - Address the reader in second person. First-person plural needs an authoring organization as its antecedent, so a single-maintainer project has none to use.
 - Use contractions wherever the sentence reads better for one. Do not force them in.

package/standards/skill.md

@@ -17,8 +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 and word choice in a skill body: `prose.md`
-- Punctuation and formatting in a skill body: `markdown.md`
+- Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
+- Punctuation, formatting, and word choice 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,8 +17,8 @@ Governs each authored standard under `standards/`: its stated jurisdiction, succ
 
 Does not govern:
 
-- The voice and word choice a standard is written in: `prose.md`
-- The punctuation and formatting a standard is written in: `markdown.md`
+- The voice, rhythm, and sentence construction a standard is written in: the `write-human` skill
+- The punctuation, formatting, and word choice 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/teach.md

@@ -20,8 +20,8 @@ Does not govern:
 - Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
 - One question measured in depth before anyone can plan against it: `groundwork.md`
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
-- Voice and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 - When a workspace opens at all, and the procedure that runs one, which belong to the surface driving it
 
 ## What a working workspace looks like

package/standards/versioning.md

@@ -16,8 +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 and word choice in any text carrying a label: `prose.md`
-- Punctuation and formatting in any text carrying a label: `markdown.md`
+- Voice, rhythm, and sentence construction in any text carrying a label: the `write-human` skill
+- Punctuation, formatting, and word choice in any text carrying a label: `markdown.md`
 
 ## Phase labels
 

package/standards/wireframes.md

@@ -17,8 +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 and word choice in wireframe prose: `prose.md`
-- Punctuation and formatting in wireframe prose: `markdown.md`
+- Voice, rhythm, and sentence construction in wireframe prose: the `write-human` skill
+- Punctuation, formatting, and word choice in wireframe prose: `markdown.md`
 
 ## What a working wireframe looks like
 
@@ -75,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` 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.
+- The Behavior and Copy prose around an ASCII block is prose and follows `markdown.md` and the `write-human` skill. 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

@@ -25,7 +25,7 @@ esac
 [ -f "$file" ] || exit 0
 
 # The audit verb owns the ban sets, so this hook carries no copy of them. The
-# awk this replaces parsed the word bans out of the project's own prose.md,
+# awk this replaces parsed the word bans out of the project's own standards,
 # hardcoded the em-dash and semicolon, and reached none of the spellings, so a
 # British spelling passed at edit time and a corpus check caught it later with
 # nothing in between explaining the difference. A ban class added to the verb
@@ -79,7 +79,7 @@ elif [ -n "$empty" ]; then
 fi
 
 if [ -n "$hits" ]; then
-  found=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite the sentence (do not lazy-swap). A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
+  found=$(printf 'Standards-audit: markdown.md violations in %s. Rewrite the sentence (do not lazy-swap). A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
   msg="${msg:+$msg$nl}$found"
 fi
 

package/standards/prose.md

@@ -1,89 +0,0 @@
----
-title: Prose reference
-description: Voice, language, what prose may claim, 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. 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, word choice, what prose may claim about its subject and its sources, 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, the form a date takes, 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`
-- The scan that applies these bans to finished text on its way out: `publish.md`
-- Code style and language conventions, which are governance rules rather than a standard
-
-## Voice
-
-- Write for a developer who is scanning, not studying. Every sentence should be understandable on first read.
-- Use active voice. Default to present tense unless past or future tense is factually correct.
-- Prioritize direct verbs and plain words, using the minimum necessary. Write `use` not `utilize`, `help` not `facilitate`, `is` not `serves as`.
-- Vary sentence length and opening structure to break uniform cadence. Do not start consecutive sentences the same way.
-- 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.
-- Front-load key information in each paragraph. Keep paragraphs concise and scannable.
-- Every sentence must provide new information. Cut redundant context.
-
-## Language
-
-- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
-- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
-- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
-- Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
-- Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
-- Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
-- Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
-- Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
-- Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
-- Do not name a person, company, or product to borrow its authority. Name a source only where the claim turns on who made it.
-- Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
-- Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
-
-The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and the bans here reach the words a sentence chooses and the claims it makes. A surface applying both reads both files.
-
-## Frontmatter descriptions
-
-When frontmatter carries a short `title` or `description` used for catalog display:
-
-- `title`: sentence case, identifies the file uniquely against its siblings in the same catalog. Proper nouns retain their casing. No trailing period.
-- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. Lead with concrete subjects, strip filler like "guide to", "overview of", or "documentation about". No trailing period, no leading article (`the`, `a`).
-- Do not mechanically reuse the H1 as the description.
-
-## Examples
-
-Each pair shows a banned pattern and its fix.
-
-```markdown
-Bad: The configuration file serves as the central hub for all build settings.
-Good: Configuration lives in `vite.config.ts`.
-```
-
-```markdown
-Bad: In order to configure the server, you'll need to ensure that the port is set.
-Good: Set `port` in the server config.
-```
-
-```markdown
-Bad: It's not just a cache. It's a system for intelligent memory management.
-Good: The cache is an LRU store. It evicts the least-recently-used entry when full.
-```
-
-```markdown
-Bad: Leveraging the retry mechanism, developers can build more resilient integrations.
-Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
-```
-
-```markdown
-Bad: It might be worth considering whether to enable caching.
-Good: Enable caching for read-heavy endpoints. Skip it for writes.
-```