chaffjs 0.22.0 → 0.24.0

package/rules/cross-doc-duplicate-definition.yaml

@@ -1,6 +1,6 @@
 id: cross-doc-duplicate-definition
 layer: L3
-status: experimental
+status: stable
 how_to_find: cross-doc-duplicate-definition
 # documents: compares the files of one run, so it runs only when chaff is given two or more files, or a folder.
 requires: [structure, documents]

package/rules/cross-doc-fact-conflict.yaml

@@ -1,6 +1,6 @@
 id: cross-doc-fact-conflict
 layer: L3
-status: experimental
+status: stable
 how_to_find: cross-doc-fact-conflict
 # documents: compares the files of one run, so it runs only when chaff is given two or more files, or a folder.
 requires: [quantities, documents]

package/rules/cross-doc-term-variant.yaml

@@ -1,12 +1,12 @@
 id: cross-doc-term-variant
 layer: L3
-status: experimental
+status: stable
 how_to_find: cross-doc-term-variant
 # documents: compares the files of one run, so it runs only when chaff is given two or more files, or a folder.
 requires: [documents]
 # The katakana words come from the language package's split. Without parts of speech only the Latin and listed words are read.
 uses: [pos]
-severity: warning
+severity: info
 
 name:
   ja: ファイルによって書き方が違う語
@@ -32,9 +32,11 @@ placeholders:
     ja: ほかのファイルの書き方
     en: the other files' spelling
 
-levels: { strict: error, normal: warning, relaxed: info }
+levels: { strict: warning, normal: info, relaxed: info }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  literature: measured by yarn rules:measure
 
 group: consistency
 summary:

package/rules/ellipsis-consistency.yaml

@@ -0,0 +1,73 @@
+id: ellipsis-consistency
+layer: L2
+status: stable
+how_to_find: ellipsis-consistency
+severity: info
+
+name:
+  ja: 省略記号の書き方が混ざっている
+  en: Ellipses written two ways
+
+why:
+  ja: 省略の記号を「……」と「・・・」、「…」と「...」のように二通りに書くと、読み手は違いに意味があるのかと迷い、別々の所から貼り合わせた文書に見えます。検索や置換でも片方を取りこぼします。どの書き方が正しいかは決めず、文書の中で少ないほうを指します。
+  en: 'An ellipsis written as "..." in some places and "…" in others makes the reader wonder whether the difference means something, and makes the document look pasted together; a search finds only one kind. chaff does not pick a side; it points at the way the document uses less.'
+
+message:
+  ja: 省略の記号を「{written}」と書いています（この文書はふつう「{usual}」。{of} 箇所のうち {count} 箇所が違う）
+  en: 'The ellipsis "{written}" here, where the document usually writes "{usual}" ({count} of {of})'
+
+how_to_fix:
+  ja: 文書の多いほうの書き方に合わせてください。
+  en: Match the way the rest of the document writes it.
+
+# 少ないほうが、省略記号の何パーセントまでなら「混ざっている」と見るか。これを超えたら、文書が使い分けている。
+levels: { strict: 49, normal: 34, relaxed: 20 }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+
+group: consistency
+summary:
+  ja: 「……」と「・・・」、「…」と「...」のように、一つの文書で省略の記号を二通りに書いている所
+  en: An ellipsis written two ways in one document, such as "..." and "…"
+example:
+  ja:
+    before: |
+      準備中です……。確認中です……。少々お待ちください・・・。
+    after: |
+      準備中です……。確認中です……。少々お待ちください……。
+  en:
+    before: |
+      Loading… Saving… Please wait...
+    after: |
+      Loading… Saving… Please wait…
+not_flagged:
+  ja: コードの中は見ません。点がさらに続く所（....、…・）は、どの書き方か決められないので数えません。少ないほうが全体の 3 分の 1 を超える文書や、二通りが同じ数の文書は、使い分けていると読んで指しません。
+  en: Code is not read. A longer run of dots ("....") is not counted, since its form is unclear. When the less common way is over a third, or the two are equally common, the document is read as using both on purpose.
+level_meaning:
+  ja: 少ないほうが {limit}% までなら指摘
+  en: reported while the less common way is at most {limit}% of the ellipses
+sources: [vale-styles]
+rewrite:
+  depth: light
+  ja:
+    direction: 指した記号だけを、文書の多いほうの書き方に替えてください。ほかは変えません。
+    pairs:
+      - before: 少々お待ちください・・・。
+        after: 少々お待ちください……。
+      - before: 結果は...まだです。
+        after: 結果は……まだです。
+    keep:
+      - 記号の前後の文
+    avoid:
+      - 省略記号を消して文を書き換える
+  en:
+    direction: Change only the marked ellipsis to the form the rest of the document uses.
+    pairs:
+      - before: Please wait...
+        after: Please wait…
+      - before: The answer is . . . not yet known.
+        after: The answer is… not yet known.
+    keep:
+      - the words around the ellipsis
+    avoid:
+      - dropping the ellipsis or rewriting the sentence

package/rules/figurative-density.yaml

@@ -0,0 +1,84 @@
+id: figurative-density
+layer: L2
+status: stable
+how_to_find: phrase-density
+word_list: figurative-phrase
+uses: [pos]
+severity: info
+
+name:
+  ja: 飾りのたとえが多い
+  en: Too many decorative figures
+
+why:
+  ja: 「まるで魔法のように動く」「呪文のようなコマンド」「おまじないとして書く」のようなたとえは、一つなら文に色を付けますが、重なると何がどう動くのかが書かれないまま文書が進みます。読み手は仕組みを知りたいのに、たとえしか受け取れません。一つ一つは誤りではないので、文書の長さあたりの数で見ます。たとえの一覧は語彙表 figurative-phrase にあり、語ごとに代わりに書くことの例が付いています。
+  en: 'A figure such as "works like magic", "a one-line incantation" or "our secret sauce" adds colour once. Piled up, the document goes on without saying what actually happens, and a reader who wants the mechanism gets only the figure. None of them is wrong alone, so the rule counts them per length of the document. The figures are in the lexicon figurative-phrase, each with what to write instead.'
+
+message:
+  ja: 「{matched}」など、飾りのたとえが 1000 字あたり {density} 個あります
+  en: '"{matched}" and other decorative figures: {density} per 1000 words'
+
+how_to_fix:
+  ja: たとえの代わりに、何がどう動くのか、何ができるのかを書いてください（まるで魔法のように設定が済む → 設定ファイルを読んで自動で済ませる）。
+  en: Replace the figure with what happens ("the config sets itself up like magic" becomes "the tool reads the config file and fills in the defaults").
+
+# 「まるで魔法のように」は一つのたとえに二語が当たるので、既定は 1000 字あたり 2 個まで。
+levels: { strict: 1, normal: 2, relaxed: 3 }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  literature: "Figures are the writer's material in literature."
+  speech: "A speaker's figures are part of the talk."
+
+group: ai-tells
+summary:
+  ja: 「まるで魔法のように」「呪文のような」「おまじない」のような、仕組みの代わりのたとえが多い所
+  en: Decorative figures such as "like magic", "incantation" and "secret sauce" piled up in place of the mechanism
+
+example:
+  ja:
+    pad: true
+    before: |
+      このツールを入れると、まるで魔法のように設定が終わります。最初の一行は呪文のようなものなので、おまじないとして書いておいてください。
+    after: |
+      このツールを入れると、設定ファイルを読んで既定の値を自動で埋めます。最初の一行は文字コードを指定する行なので、消さずに残してください。
+  en:
+    pad: true
+    before: |
+      The installer works like magic. Our secret sauce is a one-line incantation that magically fixes every path.
+    after: |
+      The installer reads your config file and fills in the defaults. The fix is one command that rewrites every path to an absolute one.
+
+not_flagged:
+  ja: 一つ一つは誤りではないので、短い文書は測りません。例を挙げる「〜のような」（A や B のような製品）は数えません。文学と講演のジャンルでは止めています。
+  en: None of these is wrong alone, so short documents are not measured. A plain comparison or example ("tools such as A and B") is not counted. The literature and speech genres turn it off.
+level_meaning:
+  ja: 1000 字あたり飾りのたとえ {limit} 個まで
+  en: up to {limit} decorative figures per 1000 words
+
+rewrite:
+  depth: register
+  ja:
+    direction: たとえを、何がどう動くのか、何ができるのかの説明に替えてください。語彙表の語ごとの書き換えの例に従い、文書に書かれていない仕組みは作りません。
+    pairs:
+      - before: このツールを入れると、まるで魔法のように設定が終わります。
+        after: このツールを入れると、設定ファイルを読んで既定の値を自動で埋めます。
+      - before: 最初の一行はおまじないとして書いておいてください。
+        after: 最初の一行は文字コードを指定する行なので、消さずに残してください。
+    keep:
+      - 書いてある事実と手順
+    avoid:
+      - 文書に書かれていない仕組みを作って書く
+      - たとえを別のたとえに替える
+  en:
+    direction: Replace each figure with what actually happens or what the thing does, following the lexicon's hint for the phrase. Do not invent a mechanism the document does not give.
+    pairs:
+      - before: The installer works like magic.
+        after: The installer reads your config file and fills in the defaults.
+      - before: Our secret sauce is a one-line incantation that fixes every path.
+        after: The fix is one command that rewrites every path to an absolute one.
+    keep:
+      - the facts and steps the document gives
+    avoid:
+      - inventing a mechanism the document does not describe
+      - swapping one figure for another

package/rules/ime-residue.yaml

@@ -0,0 +1,55 @@
+id: ime-residue
+layer: L1
+status: stable
+how_to_find: ime-residue
+languages: [ja]
+severity: warning
+
+name:
+  ja: 変換し損ねた英字
+  en: A Latin letter left by the input method
+
+why:
+  ja: 「おもしrおい」「対応sた」のように、日本語の語の中に英字が一字だけ残るのは、ローマ字入力で押したキーが仮名にならなかった跡です。読み手はその語で止まり、検索にも当たりません。打ち間違いなので、どちらの書き方が正しいかの話ではありません。
+  en: "A single Latin letter inside a Japanese word (おもしrおい for おもしろい) is a key pressed in romaji input that never became kana. The reader stops at the word, and search does not find it. It is a typing slip, not a style."
+
+message:
+  ja: 日本語の語の中に英字「{letter}」が一字だけあります（変換し損ねた跡）
+  en: 'A lone Latin letter "{letter}" inside a Japanese word, left by the input method'
+
+how_to_fix:
+  ja: 英字を消して、語を打ち直してください（おもしrおい → おもしろい）。
+  en: Delete the letter and retype the word (おもしrおい → おもしろい).
+
+levels: { strict: error, normal: warning, relaxed: info }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+
+group: slips
+summary:
+  ja: 「おもしrおい」「対応sた」のような、日本語の語の中に一字だけ残った英字
+  en: A single Latin letter left inside a Japanese word by the input method, as in おもしrおい
+example:
+  ja:
+    before: |
+      この資料はとてもおもしrおいです。
+    after: |
+      この資料はとてもおもしろいです。
+
+not_flagged:
+  ja: 大文字（A 社、B さん）、二字以上の英字（while 文、note）、コードの中は指しません。後ろに助詞が続く一字（変数 x が、まず x を、を x で）は変数の名と読み、一字の後ろが漢字のもの（の x 座標）も指しません。片仮名の後ろの一字（サイズ m、プラン b）は記号と読み、パスの中（/docs/…）も見ません。
+  en: Capitals (A社, Bさん), runs of two or more letters (while文, note) and code are not reported. A letter followed by a particle (変数xが, まずxを, をxで) is read as the name of a variable, and a letter followed by a kanji (のx座標) is not reported either. A letter after katakana (サイズm, プランb) is read as a label, and paths (/docs/…) are not read.
+sources: [textlint-ja-presets]
+rewrite:
+  depth: light
+  ja:
+    direction: 残った英字を消して、前後の仮名から語を打ち直してください。語が決められないときは書き手に尋ねます。
+    pairs:
+      - before: この資料はとてもおもしrおいです。
+        after: この資料はとてもおもしろいです。
+      - before: 申請に対応sたことを報告します。
+        after: 申請に対応したことを報告します。
+    keep:
+      - 文のほかの語
+    avoid:
+      - 前後の語まで書き換える

package/rules/lookalike-character.yaml

@@ -0,0 +1,82 @@
+id: lookalike-character
+layer: L1
+status: stable
+how_to_find: lookalike-character
+severity: warning
+
+name:
+  ja: 見た目が同じで別の字
+  en: Look-alike character
+
+why:
+  ja: 部首の字（⼈ U+2F08）や互換漢字は、ふつうの「人」と同じに見えて別の字です。濁点を別の字にした「か＋゛」（macOS のファイル名や、そこからコピーした文に多い）も、「が」と同じに見えて別の並びです。どれも検索、並べ替え、辞書引き、表記の照合から漏れ、読み手には直す所が見えません。PDF からのコピーや、入力の変換で入ります。コードの中も見ます。
+  en: "A Kangxi radical (⼈ U+2F08) looks like the ordinary 人 and is another character; so is a CJK compatibility ideograph. A letter written as a base and a separate combining mark (e + U+0301, common in macOS file names and text copied from them) looks like é and is another sequence. Search, sorting, dictionaries and spelling checks all miss them, and the reader cannot see what to fix. They come from PDF copies and input methods. Code is checked too."
+
+message:
+  ja: 「{written}」（{code}）は「{usual}」と同じに見える別の字です
+  en: '"{written}" ({code}) looks like "{usual}" but is another character'
+
+messages:
+  radical:
+    ja: 「{written}」（{code}）は部首の字です。ふつうの「{usual}」と書きます
+    en: '"{written}" ({code}) is a radical, not the ordinary "{usual}"'
+  compatibility:
+    ja: 「{written}」（{code}）は互換漢字です。ふつうの「{usual}」と書きます
+    en: '"{written}" ({code}) is a compatibility ideograph, not the ordinary "{usual}"'
+  decomposed:
+    ja: 「{written}」は字と記号が分かれています（{code}）。一字の「{usual}」と書きます
+    en: '"{written}" is a letter and a separate mark ({code}), not the single letter "{usual}"'
+  spacing-mark:
+    ja: 「{written}」は濁点・半濁点を別の字で書いています（{code}）。一字の「{usual}」と書きます
+    en: '"{written}" writes the voicing mark as a separate character ({code}), not the single letter "{usual}"'
+
+how_to_fix:
+  ja: その字を消して、ふつうの字を打ち直してください。文書全体を NFC に正規化しても直ります（部首の字は NFKC）。
+  en: Delete the character and type the ordinary one. Normalising the document to NFC also fixes it (NFKC for radicals).
+
+levels: { strict: error, normal: warning, relaxed: info }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+
+group: slips
+summary:
+  ja: 部首の字（⼈）、互換漢字、字と分かれた濁点（か＋゛）のような、ふつうの字と同じに見える別の字
+  en: A character that looks like an ordinary one but is another, such as a Kangxi radical (⼈ for 人) or a letter and a separate combining mark
+example:
+  ja:
+    before: "申込書は総務課の⼭田さんへ送ってください。\n"
+    after: |
+      申込書は総務課の山田さんへ送ってください。
+  en:
+    before: "Send the form to the café office.\n"
+    after: |
+      Send the form to the café office.
+
+not_flagged:
+  ja: 一字にまとまる形の無い組み合わせ（字に付いた異体字の指定、合成済みの形の無いアクセント）と、Unicode が別の字として持つ互換漢字（﨑 など）は指しません。
+  en: Combinations with no single precomposed form (a variation selector after a character, an accent with no precomposed letter) and compatibility ideographs that Unicode keeps as their own characters (﨑) are not reported.
+sources: [textlint-ja-presets]
+rewrite:
+  depth: light
+  ja:
+    direction: 指した字だけを、同じに見えるふつうの字に打ち直してください。ほかの字は変えません。
+    pairs:
+      - before: "総務課の⼭田さんへ送ってください。"
+        after: 総務課の山田さんへ送ってください。
+      - before: "がいしゃに送ります。"
+        after: がいしゃに送ります。
+    keep:
+      - 字の並びと文の意味
+    avoid:
+      - 同じに見えるからと、指した字をそのまま残す
+  en:
+    direction: Retype only the marked character as the ordinary one it looks like. Change nothing else.
+    pairs:
+      - before: "Send it to the café office."
+        after: Send it to the café office.
+      - before: "The résumé is attached."
+        after: The résumé is attached.
+    keep:
+      - the words and their order
+    avoid:
+      - leaving the marked character because it looks right

package/rules/numbered-generic-heading.yaml

@@ -0,0 +1,111 @@
+id: numbered-generic-heading
+layer: L1
+status: stable
+how_to_find: generic-heading
+word_list: generic-heading-label
+requires: [markdown]
+severity: info
+
+name:
+  ja: 札と番号だけの見出し
+  en: Headings that are only a label and a number
+
+why:
+  ja: 「メリット1」「メリット2」「ポイント3」のように札と番号だけの見出しは、目次や見出しの一覧で読んでも、その節に何が書いてあるかが分かりません。読み手は節を開くまで中身を知れず、あとで探すこともできません。型をなぞって書いた文書に多い形です。札は語彙表 generic-heading-label にあり、手順の札（ステップ1）は順番そのものが中身なので入れていません。
+  en: 'Headings such as "Benefit 1", "Benefit 2" and "Tip 3" say nothing about their sections. A reader scanning the table of contents learns nothing until they open each one, and cannot find a section again later. Documents written to a template are full of them. The labels are in the lexicon generic-heading-label; step labels ("Step 1") are left out, since in a procedure the order is the content.'
+
+message:
+  ja: 見出し「{heading}」は札と番号だけで、節の中身が分かりません（そういう見出しが {count} 個）
+  en: 'The heading "{heading}" is only a label and a number and says nothing about the section ({count} such headings)'
+
+how_to_fix:
+  ja: 札の後ろに、その節で言うことを書いてください（メリット1 → メリット1：設定が要らない、または 設定が要らない）。
+  en: 'Say what the section says ("Benefit 1" becomes "Benefit 1: no setup" or simply "No setup needed").'
+
+levels: { strict: 1, normal: 2, relaxed: 3 }
+
+use_for: [blog, business, technical, docs, academic, legal, literature, speech]
+off_for:
+  literature: "A literary work names its parts as it likes."
+  speech: "A transcript has no headings of its own."
+
+group: structure
+summary:
+  ja: 「メリット1」「ポイント2」「Benefit 3」のように、札と番号だけで中身を言わない見出しが並ぶ所
+  en: Headings such as "Benefit 1" and "Tip 2" that are only a label and a number
+
+example:
+  ja:
+    before: |
+      # 新しい会議室予約の仕組み
+
+      ## メリット1
+
+      空き状況がすぐ分かります。
+
+      ## メリット2
+
+      予約の取り消しが一度で済みます。
+    after: |
+      # 新しい会議室予約の仕組み
+
+      ## 空き状況がすぐ分かる
+
+      空き状況がすぐ分かります。
+
+      ## 取り消しが一度で済む
+
+      予約の取り消しが一度で済みます。
+  en:
+    before: |
+      # The new room booking system
+
+      ## Benefit 1
+
+      You can see free rooms at once.
+
+      ## Benefit 2
+
+      You can cancel a booking in one step.
+    after: |
+      # The new room booking system
+
+      ## Free rooms at a glance
+
+      You can see free rooms at once.
+
+      ## One-step cancelling
+
+      You can cancel a booking in one step.
+
+not_flagged:
+  ja: 札の後ろに題を足した見出し（メリット1：設定が要らない）、手順・理由・課題の見出し（ステップ1、理由2、課題3）、章や節の番号（第1章）は、番号で引かれる単位なので指しません。Markdown の見出しだけを読みます。
+  en: 'A heading with a title after the label ("Benefit 1: no setup"), step, lesson, reason and feature headings ("Step 1", "Lesson 2", "Reason 3"), and chapter or section numbers ("Chapter 1") are not reported: each is a unit cited by its number. Only Markdown headings are read.'
+level_meaning:
+  ja: 札と番号だけの見出しが {limit} 個から指摘
+  en: reported from {limit} such headings
+
+rewrite:
+  depth: structure
+  ja:
+    direction: 札と番号だけの見出しに、その節で言うことを一言で書いてください。節の本文から言葉を取り、本文に無いことは足しません。
+    pairs:
+      - before: "## メリット1"
+        after: "## 空き状況がすぐ分かる"
+      - before: "## ポイント2"
+        after: "## 取り消しは前日まで"
+    keep:
+      - 節の順番と本文
+    avoid:
+      - 本文に書かれていない中身を見出しに書く
+  en:
+    direction: Give each label-and-number heading a few words that say what its section says, taken from the section itself.
+    pairs:
+      - before: "## Benefit 1"
+        after: "## Free rooms at a glance"
+      - before: "## Tip 2"
+        after: "## Cancel by the day before"
+    keep:
+      - the order of the sections and their text
+    avoid:
+      - putting a claim in a heading that the section does not make

package/rules/undefined-acronym.yaml

@@ -18,6 +18,7 @@ extra_word_lists:
     name-title,
     date-time-unit,
     http-method,
+    reference-list-heading,
   ]
 uses: [pos]
 severity: info

package/rules/unit-spacing-consistency.yaml

@@ -0,0 +1,74 @@
+id: unit-spacing-consistency
+layer: L2
+status: stable
+how_to_find: unit-spacing-consistency
+severity: info
+
+name:
+  ja: 数と単位の間の空白が混ざっている
+  en: Units spaced two ways
+
+why:
+  ja: 一つの文書で「5 GB」と「5GB」のように、数と単位記号の間を空ける所と詰める所が混ざると、読み手は違いに意味があるのかと迷い、別々の所から貼り合わせた文書に見えます。検索でも片方を取りこぼします。どちらが正しいかは決めず、単位ごとに、文書の中で少ないほうを指します。
+  en: 'A document writing "5 GB" in one place and "5GB" in another makes the reader wonder whether the difference means something, looks pasted together, and splits a search. chaff does not pick a side; unit by unit, it points at the way the document uses less.'
+
+message:
+  ja: 「{written}」と書いています（この文書はこの単位をふつう「{usual}」のように書きます。{of} 箇所のうち {count} 箇所が違う）
+  en: '"{written}" here, where the document usually writes this unit like "{usual}" ({count} of {of})'
+
+how_to_fix:
+  ja: 文書の多いほうの書き方に合わせてください。
+  en: Match the way the rest of the document writes units.
+
+# 少ないほうが、数と単位の組の何パーセントまでなら「混ざっている」と見るか。これを超えたら、文書が使い分けている。
+levels: { strict: 49, normal: 34, relaxed: 20 }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+
+group: consistency
+summary:
+  ja: 「5 GB」と「5GB」のように、一つの文書で数と単位記号の間を空けたり詰めたりしている所
+  en: A number and a unit symbol spaced in some places and not in others, such as "5 GB" and "5GB"
+example:
+  ja:
+    before: |
+      容量は 5 GB、転送量は 10 GB、上限は 20GB です。
+    after: |
+      容量は 5 GB、転送量は 10 GB、上限は 20 GB です。
+  en:
+    before: |
+      Storage is 5 GB, transfer is 10 GB and the cap is 20GB.
+    after: |
+      Storage is 5 GB, transfer is 10 GB and the cap is 20 GB.
+
+not_flagged:
+  ja: 単位記号の一覧にあるものだけを見ます。一字の記号（m、s、g）、パーセント、温度（°C）は、空けない書き方が別に定着しているので数えません。語で書いた単位（5 時間、5 hours）、コードの中、版や番地の中の数（1.2.3GB）も見ません。単位ごとに比べるので、「5 GB」と「500ms」が並んでも混在とは読みません。ノーブレークスペースも空白と数えます。少ないほうが 3 分の 1 を超える文書や、二通りが同じ数の文書は、使い分けていると読んで指しません。
+  en: Only the unit symbols on chaff's list are read. One-letter symbols (m, s, g), the percent sign and temperatures (°C) are left out, since many styles write them unspaced on purpose. Units written as words (5 hours), code, and numbers inside versions or addresses (1.2.3GB) are not read. Each unit is compared with itself, so "5 GB" next to "500ms" is not a mix. A no-break space counts as a space. When the less common way is over a third, or the two are equally common, the document is read as using both on purpose.
+level_meaning:
+  ja: 少ないほうが {limit}% までなら指摘
+  en: reported while the less common way is at most {limit}% of the units
+sources: [vale-styles]
+rewrite:
+  depth: light
+  ja:
+    direction: 指した所だけ、数と単位の間を文書の多いほうに合わせてください。ほかは変えません。
+    pairs:
+      - before: 上限は 20GB です。
+        after: 上限は 20 GB です。
+      - before: 間隔は 500 ms です。
+        after: 間隔は 500ms です。
+    keep:
+      - 数と単位そのもの
+    avoid:
+      - 単位を別の単位に換える
+  en:
+    direction: Add or remove the space between the number and the unit at the marked place only, to match the rest of the document.
+    pairs:
+      - before: The cap is 20GB.
+        after: The cap is 20 GB.
+      - before: The interval is 500 ms.
+        after: The interval is 500ms.
+    keep:
+      - the number and the unit
+    avoid:
+      - converting the unit

package/skills/chaff/SKILL.md

@@ -23,6 +23,10 @@ read. A contract checked as a blog post gets wrong findings, so choose the genre
    `npx chaffjs init --genre legal/contract` writes it into `chaff.yaml` (always pass `--genre`: without it,
    `init` asks at a terminal).
 4. The header's first line shows the genre used and where it came from. Check it before trusting the findings.
+5. With the genre set, the report opens with the genre's guide: what a good document of that kind does, and the
+   rules that matter most for it. Read it first, before any finding, and hold the draft (or your rewrite) to each
+   line; most of it is what no rule can check. The team may have changed it with `guide:` in `chaff.yaml`. A
+   guessed or default genre shows no guide.
 
 A rule the genre turns off is listed under "did not run" with the genre as the reason. That is the preset's
 choice, not a gap; turn it back on (`rules:` in `chaff.yaml`) only when the person asks.
@@ -112,6 +116,8 @@ generated. chaff never rewrites; the rewriting is yours.
 **Start with the plan.** Run `npx chaffjs fix-plan <file>` (with the genre's `--genre`; `--json` to
 read it as data). It prints, in the document's language:
 
+- the genre's guide first, when the genre is set: what a good document of the kind does, the lines your rewrite
+  is held to;
 - the constraints: keep facts, numbers, conditions and names; add no fact; ask the writer instead of inventing a
   specific; two passes at most;
 - the recommended mode and why, and the document-level signals with the outline's numbers;

package/src/api.ts

@@ -138,6 +138,15 @@ export const defineRule = (spec: RuleSpec): Rule => ({ ...spec, apiVersion: API_
 /** A word list in each language it has words for: { ja: [...], en: [...] }. A string is an entry with only a pattern. */
 export type LexiconSpec = Readonly<Record<string, readonly (string | LexiconEntry)[]>>;
 
+/** Lines of a genre guide: one line or a list, the same in every language, or by language ({ ja: [...], en: [...] }). */
+export type GuideText = string | readonly string[] | Readonly<Record<string, string | readonly string[]>>;
+
+/**
+ * Changes to the genre guides chaff prints before the findings, by genre or group (blog/tech, legal): replace sets the
+ * lines, add puts lines after them, off leaves the genre with none.
+ */
+export type GuideSpec = Readonly<Record<string, "off" | { readonly replace?: GuideText; readonly add?: GuideText }>>;
+
 /** A house style a plugin ships: rule levels and options, and the guideline it follows. */
 export type StyleSpec = {
   readonly id: string;
@@ -146,6 +155,8 @@ export type StyleSpec = {
   readonly source: { readonly title: Text; readonly url: string };
   readonly rules?: Readonly<Record<string, "strict" | "normal" | "relaxed" | "off">>;
   readonly options?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  /** Its changes to the genre guides, while the style is chosen. */
+  readonly guide?: GuideSpec;
 };
 
 /**
@@ -158,6 +169,8 @@ export type PluginSpec = {
   readonly rules?: readonly (Rule | RuleSpec | Readonly<Record<string, unknown>>)[];
   readonly lexicons?: Readonly<Record<string, LexiconSpec>>;
   readonly styles?: readonly StyleSpec[];
+  /** Its changes to the genre guides, whenever the plugin is loaded. */
+  readonly guide?: GuideSpec;
 };
 
 export type Plugin = PluginSpec & { readonly apiVersion: number };

package/src/cli-args.ts

@@ -14,6 +14,9 @@ export const withExperimental = <T extends { readonly experimental: boolean }>(c
   experimental: config.experimental || args.includes("--experimental"),
 });
 
+/** Whether this run shows the genre's guide: everywhere it would, unless --no-guide leaves it out. */
+export const showsGuide = (args: readonly string[]): boolean => !args.includes("--no-guide");
+
 /** The settings with each --include <glob> added to chaff.yaml's include: the command line widens a directory walk as chaff.yaml can. */
 export const withIncludes = <T extends { readonly include?: readonly string[] | undefined }>(config: T, args: readonly string[]): T => {
   const given = args.flatMap((arg, index) => (index > 0 && args[index - 1] === "--include" && !arg.startsWith("--") ? [arg] : []));

package/src/cli-text.ts

@@ -56,6 +56,7 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
                                  誤った指摘・見逃しの報告の下書きを作る（何も送らない。--with-config で chaff.yaml 全体も載せる）
 
   --compact         エンジニア向けの 1 行形式
+  --no-guide        ジャンルを決めたときに最初に出す、そのジャンルの指針を出さない
   --experimental    試験中の rule も動かす
   --genre <ジャンル>  この実行だけジャンルを決める（chaff.yaml より優先）
   --show-baseline   棚上げした分も含めて全部見る
@@ -101,6 +102,7 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
                                  draft a report of a wrong or missed finding (sends nothing; --with-config adds all of chaff.yaml)
 
   --compact         one line per finding, for engineers
+  --no-guide        leave out the genre's guide, which comes first when the genre is set
   --experimental    run the experimental rules too
   --genre <genre>   the genre for this run only (wins over chaff.yaml)
   --show-baseline   show the shelved findings too