asciidoc-pubkit 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6148912a889b61a943c121c307ae696c49f861f7cb734265af0b1a9333d50966
-  data.tar.gz: ce07e6f2d66c7ab3e23a8dd39325b297f9f3d3f6c715fb001c2604052307f999
+  metadata.gz: 344dfb065e1bc2a69918b59ba37caa6a4857f89a8e8b52aab65614ad0f3d0cb4
+  data.tar.gz: 0ab6f311b266bb760e7b06ee614fe8e3785483f42117e25290d50755f94ac17a
 SHA512:
-  metadata.gz: a08ca5477ee8785bbe7623a108e2cd22ad8c1f4c6900e7500d446502674007db5b29192c9e02abdeacb931a26a78a45070b6f19b57c0de51c4bd20d2da884afe
-  data.tar.gz: ee0b90c82c362f7b0da5b1807cf187ad2d330c24a5ce11cfa599f25d50c35fa99814bb154d148f3b747c87bfeaf965dea76f22e283e8e2d53685341203239bf7
+  metadata.gz: 5180830a2ecc63aca2a4e3046ad9fed14a0dd5195c043a6af995f228082d79efadf3aaa19c89373b45d55e84dbbdd458ad7f89b98db4f25198d5b68bb9667681
+  data.tar.gz: 22ef17dde95619bb6c52fd99848e6787d5acfa702fef72cb69a0bb943753e93835b277a78660f7d121ec09506dc2caa7218fae77564d7ffa406485765c590157

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 1.2.2 - 2026-10-12
+
+- Distinguish explanatory guidance, real checking procedures, runtime behavior,
+  and learning objectives in shared Japanese criteria and the evaluation rubric.
+  Narrow the ambiguous scope-guide keep example to an actual user exercise and
+  add seven calibration pairs (77 total), including ownership and unsupported
+  actor controls. Add the classification step to the bundled review skill.
+  Detector rules, automatic replacement and mechanical verification are unchanged;
+  old sessions retain saved criteria. AI proofreading improvement is unmeasured.
+
+## 1.2.1 - 2026-10-12
+
+- Compare faithful technical terminology independently of capability/behavior
+  preservation; honor author wording preferences even for synonyms. Reject keep
+  rationales based on unsupported stronger alternatives. Clarify selection,
+  partition, logical separation, language independence and workflow integration
+  in shared criteria, generated prompts and the bundled review skill. Add advisory
+  `組み込む` candidates in MeCab/literal modes and eleven calibration pairs (70
+  total). Pass editorial constraints to the optional evaluator without gold
+  judgments. Old sessions retain saved criteria; mechanical verification is
+  unchanged. No AI proofreading improvement has been measured.
+
 ## 1.2.0 - 2026-10-12
 
 - Require concrete alternative comparisons for broad or everyday wording in

data/README.md

@@ -16,7 +16,7 @@ and books on health, exercise, and sports science published under
 The experience informs the toolkit's writing criteria, contextual review prompts,
 and checks for preserving manuscript content during revision.
 
-Version 1.2.0 provides document inspection, explicit prose-only mechanical
+Version 1.2.2 provides document inspection, explicit prose-only mechanical
 replacements, and Japanese manuscript review. Inspect a book's outline,
 metadata, and local cross-references; preview and apply your replacement rules;
 then review and verify edits against a saved baseline.
@@ -26,7 +26,7 @@ Japanese manuscript excerpts and rule terms retain their original text.
 
 ## Available features
 
-The following commands are available in version 1.2.0.
+The following commands are available in version 1.2.2.
 
 | Feature | Commands | Behavior |
 | --- | --- | --- |
@@ -48,8 +48,14 @@ The following commands are available in version 1.2.0.
 The 1.2.0 [sentence-ending guidance](docs/writing.md#writing-commands)
 adds contextual revision and keep examples, preserving capabilities, uncertainty,
 comparison strength, and body sentences separately from heading form. It adds
-no detector terms or automatic replacements; development calibration includes
-59 pairs, without a measured claim of improved AI proofreading.
+no detector terms or automatic replacements. Version 1.2.1 includes 70
+calibration pairs, without a measured claim of improved AI proofreading.
+
+Version 1.2.2 separates content guidance from actual checks and
+learning objectives, honoring each author's explanatory voice. Development
+calibration has 77 pairs, including valid exercises and runtime checks;
+detector rules and mechanical verification are unchanged. See
+[prose evaluation](docs/prose-evaluation.md) for validation limits.
 
 The 1.2.0 [default rules](docs/rules-and-coverage.md) add `流れ` as an
 `abstract-reference` hint for prose and list text. Review processing order,
@@ -62,6 +68,8 @@ everyday wording. Review prompts reject automatic keep judgments and passage
 summaries used as candidate decisions; missing comparisons remain pending.
 Verification continues to check mechanical preservation only.
 
+Version 1.2.1 [compares terminology independently of modality](data/writing/ja/criteria.md#compare-terminology-independently-of-modality), honors author terminology preferences, and adds advisory `組み込む` candidates. See [faithful terminology comparisons](docs/review-workflow.md#faithful-terminology-comparisons).
+
 Version 1.0.1 extended the [shared writing criteria](docs/writing.md#writing-commands)
 with structural comparison before and after revision and preservation of sentence
 functions and plain or polite style. The [development evaluation](docs/prose-evaluation.md)
@@ -166,7 +174,7 @@ asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
 
 Existing review sessions require the exact tool version that created them.
 Before upgrading, finish ongoing reviews with that version or preserve their
-baselines and start a new review in a separate directory with v1.2.0. A new
+baselines and start a new review in a separate directory with v1.2.2. A new
 scan cannot verify preservation relative to an earlier baseline.
 
 ## Documentation

data/data/review-rules.ja.yml

@@ -95,6 +95,11 @@ terms:
     - 作れる
     - 作れます
     - 作れません
+    - 組み込む
+    - 組み込みます
+    - 組み込めます
+    - 組み込まない
+    - 組み込めません
     - 組み立てられます
     - 組み合わせます
     - 積み重なります
@@ -150,7 +155,10 @@ terms:
     question: Identify the purpose, operation, and result, then compare a more precise
       verb or established technical term using the shared criteria. An understandable
       original is not by itself a reason to keep it. Record the alternative and the
-      passage-specific comparison. Preserve negation, conditions, and responsibility.
+      passage-specific comparison. Compare faithful alternatives with the same modality;
+      synonymy alone is not a keep reason when technical terminology is requested.
+      Do not justify keep by rejecting an unsupported stronger alternative.
+      Preserve negation, conditions, and responsibility.
   vague-degree:
     terms:
     - 浅い
@@ -306,6 +314,9 @@ verbs:
   - 渡す
   決まる:
   - 決まる
+  組み込む:
+  - 組み込む
+  - 組み込める
   組み立てる:
   - 組み立てる
   組み合わせる:

data/data/writing/ja/criteria.md

@@ -9,6 +9,7 @@
 - Explain metaphorical operations from evidence
 - Distinguish instructions, behavior, and capabilities
 - Review sentence endings by their role
+- Separate explanatory guidance from actual checks
 - Make relationships explicit
 - Compare structure before and after revision
 - Keep claims within their evidence and purpose
@@ -232,6 +233,38 @@ require polite style. Resolve unintended style mixing separately from each
 sentence's function; changing `する` to `します` must not change advice into
 an asserted operation. Do not vary endings just to make these functions uniform.
 
+## Compare terminology independently of modality
+
+Preserve whether a sentence describes a capability, actual behavior, a condition,
+or an obligation while independently choosing the most accurate wording.
+`選べます → 選択できます` preserves capability; it is not the same change as
+`選べます → 選びます`. When the operation is technical selection, prefer
+`選択できます`, especially when the author requests technical terminology.
+An alternative need not change the facts to improve terminological consistency.
+"Same meaning" and "the referent is clear" alone do not justify keep. An explicit
+terminology preference takes precedence over an otherwise acceptable plain synonym.
+
+Compare the strongest faithful alternative, not an unsupported or shortened one
+that is easy to reject. Rejecting `物理的に隔離する` does not justify keeping
+`分ける` when `別の処理として実装する` explains the supported operation.
+Do not remove conditions or information from an alternative and then use that
+loss as the reason to retain the original. Compare full sentences or paragraphs
+with the same facts, modality and author requirements.
+
+| Wording | Operation-specific comparison |
+| --- | --- |
+| `次の操作を選べます` | `次の操作を選択できます` preserves the available choice and names the selection operation. |
+| `データを複数の部分に分けます` | `データを分割します` describes partitioning one object; do not use it for every separation. |
+| `許可判断と出力検査を分けています` | Identify both purposes and timings: `操作前の許可判定と、モデル入力前の出力検査を別の処理として実装しています`. Do not invent physical isolation. |
+| `両者の実装言語を分けられます` | `呼び出し元を、実行基盤とは異なる言語で実装できます` states language independence. Languages themselves are not partitioned. |
+| `固定した処理へ行動選択を組み込めます` | Name the workflow stage, the actor selecting operations, the input used for selection, and the limits on delegated operations. A vague `統合できます` or `実装できます` alone is not an improvement. |
+
+`組み込む` is not a banned word. Library embedding can be an established operation
+when the host application, API and integration method are specified. Retain a
+plain verb only after comparing the faithful alternative and explaining a real
+loss or a context-specific readability benefit consistent with author preferences.
+A failed candidate comparison is pending, not evidence that the original is best.
+
 ## Review sentence endings by their role
 
 Read the complete sentence and neighboring sentences before judging its ending.
@@ -239,13 +272,13 @@ First identify whether it announces the section's scope, describes an actual
 operation, offers a capability, gives a checking procedure, or reports history
 or a future expectation. Then name its actor, object, condition, and consequence.
 Revise only when a more direct explanation preserves those relationships;
-otherwise retain the original wording and explain its role.
+otherwise compare the wording independently of its sentence role before retaining it.
 
 | Ending and context | Decision to consider |
 | --- | --- |
-| `注目します`, `明らかにします`, `確認します`, or `たどります` in an introduction | Keep a useful scope or reading-order guide. If it only repeats an announcement, state the supported comparison, operation, or question directly; do not invent its answer. |
+| `注目します`, `明らかにします`, `確認します`, or `たどります` in an introduction | Keep useful subject and reading-order guidance, but separately assess its actor and predicate. A useful sequence alone does not justify retaining `確認します`; distinguish content guidance from an actual exercise or check and honor the author's explanatory voice. If it only repeats an announcement, state the supported subject directly without inventing its answer. |
 | `戻します` or `組み立てます` in an operation description | Keep it when the transferred result, recipient, or constructed input is clear. Do not replace it with a noun or jargon merely to vary the ending. |
-| `使えます`, `組み込めます`, `選べます`, or `作れます` | Preserve the available option and its conditions. Changing to `使います` or `選びます` can falsely assert actual or automatic execution. |
+| `使えます`, `組み込めます`, `選べます`, or `作れます` | Preserve the available option and its conditions, not necessarily the original verb. Compare an equally potential technical expression or a concrete explanation; do not use the risks of `使います` or `選びます` to reject `適用できます` or `選択できます`. |
 | `分かりません` | Identify whether the missing evidence prevents judgment, confirmation, or identification. Use `判断できません` or `確認できません` only when that operation fits; preserve what remains unknown. |
 | `別です` or `同じではありません` | Name the compared objects and the property, purpose, or evidence that differs. Distinguish definite non-identity from insufficient evidence to infer a result. |
 | `確認します` or `調べます` in a procedure | Keep an actual check, including its target, condition, and timing. Do not turn it into a capability or a claim that the check succeeded. |
@@ -257,8 +290,10 @@ Both retain the missing evidence and the same judgment target. By contrast,
 `処理結果が分かりません` cannot become `処理は失敗しました`: an unknown
 outcome is not an established failure.
 
-Retain `利用者は候補Aと候補Bから選べます` when it states an available choice;
-`利用者は候補Aと候補Bから選びます` would assert that selection occurs. Retain
+`利用者は候補Aと候補Bから選べます` states an available choice;
+`利用者は候補Aと候補Bから選択できます` retains that choice while using technical
+selection wording. Compare this faithful alternative before keeping the plain verb.
+`利用者は候補Aと候補Bから選びます` would instead assert that selection occurs. Retain
 `実行側はツール結果をモデルへ戻します` when it describes the transfer;
 `実行結果のフィードバック` would lose the sentence's actor and predicate.
 
@@ -275,6 +310,43 @@ removing their predicates. A proposed ending alone cannot supply new subjects,
 mechanisms, constraints, or guarantees; obtain those from the actual passage
 and its evidence. Record meaningful keep decisions as well as revisions.
 
+## Separate explanatory guidance from actual checks
+
+Classify the complete sentence before choosing its verb: content guidance,
+an actual checking procedure, runtime behavior, or a reader's learning objective.
+The book explaining a subject, a reader checking evidence, and a program
+validating state are different actors and actions. Read the whole paragraph and
+neighboring sentences, including inflections such as `確認し`, before judging an
+ending. Do not mix the book's explanation with the reader's `理解します` as if
+the book performed that learning. Present a learning objective explicitly when
+that is the sentence's purpose; do not mechanically rewrite every objective.
+
+When the author requests explanatory narration, compare `説明します`,
+`示します`, or `比較します` for content guidance. For example, a chapter guide
+such as `本章では、依頼の受付と結果の返却を確認します` can become
+`本章では、依頼の受付と結果の返却を説明します`. A clear subject or useful
+reading sequence does not resolve an ambiguous checking actor or justify keep.
+Apply the book's voice rather than banning all uses of `確認` in introductions.
+An actual exercise such as `この演習では、利用者が接続設定を確認します`
+can retain its checking verb and explicit actor.
+
+For genuine checks, identify the supported actor, target, conditions, and timing
+from the passage. Compare equally faithful wording such as `照合します`,
+`検査します`, `参照します`, or an explicit actor plus `確認します`; choose a
+more specific operation only when evidence establishes it. Use preceding
+sentences or table column roles when they already identify the actor, rather
+than repeating subjects mechanically. Missing actor evidence stays unresolved;
+do not invent automatic execution or assign responsibility from the book's topic.
+Do not turn a program's runtime check into only a developer's test, a connection
+owner's shutdown responsibility into a reader's observation, or an unknown
+result into confirmed completion. Naming an actor adds no guarantee.
+
+Choose `説明` and `解説` by their purpose and the author's terminology policy.
+Content guidance can use `説明`, while in-depth background or design discussion
+can use `解説`; do not make that distinction a universal replacement rule.
+Preserve tool or Skill description data, formal titles, quotations, and code
+identifiers. Compare the actual paragraph-level alternative before keeping it.
+
 ## Make relationships explicit
 
 Inspect a sentence when it:

data/docs/explanatory-guidance-research.md

@@ -0,0 +1,174 @@
+# Explanatory guidance and checking actors: research and proposal
+
+Status: implemented for v1.2.2 on 2026-10-12. Release authorized separately after the source update.
+The proposal below is retained as design evidence. Shared criteria, the judge
+rubric, eight affected calibration examples (seven new, one narrowed), tests,
+and bundled/publisher-local skill instructions were updated. Detector rules,
+installed gem/skill versions, old sessions and manuscripts were not changed.
+Validation results are recorded separately from the original proposal.
+Research date: 2026-10-12. Pubkit baseline: `095b06d` (v1.2.1).
+Publisher evidence: cybergarage-pub commit `909de49833`, limited Orbit review.
+
+This proposal separates a book's description of its contents from a reader's
+checking procedure and a program's runtime checks. The first implementation
+should update shared criteria, calibration examples, and review-workflow
+instructions without changing detector rules, automatic replacement behavior,
+verification semantics, or installed skills.
+
+## Evidence and limits
+
+The Orbit pass reviewed 193 source lines containing `確認します` across its
+active manuscripts. It revised 49 matching lines, retained 144 after individual
+comparisons, and revised two neighboring lines containing `確認し` and
+`理解します`. These are author-specific editorial decisions from one book,
+not measured detector accuracy or proof that another book needs the same edits.
+The target expressions span 129 selected prose paragraphs and 56 protected
+table lines. Book guidance, user approval, runtime checks, and test procedures
+must not receive one lexical replacement rule.
+
+The owning sources inspected in pubkit are:
+
+- `data/writing/ja/criteria.md`, "Review sentence endings by their role": it
+  already distinguishes scope announcements, operations, capabilities, checks,
+  and history, but recommends keeping useful scope/reading-order guidance for
+  introductory `確認します`. This does not explicitly assess a switch from the
+  book's explanatory voice to a reader's learning or checking activity.
+- `test/fixtures/prose_evaluation.ja.json`, `ending-scope-guide-kept`: the source
+  and accepted unchanged revision are `本節では、接続設定、依頼の送信、終了確認の順に手順を確認します。`.
+  Its reason rewards concrete reading order without resolving who performs a
+  check. This example should be narrowed rather than teaching unconditional keep.
+- `test/prose_benchmark_test.rb`: fixture integrity, required axes, and unchanged
+  keep pairs are checked. These tests do not measure an AI's editorial judgment.
+- `benchmark/prose.rb` and `docs/prose-evaluation.md`: optional AI trials keep
+  detector scores separate from readability and preservation. The judge receives
+  editorial constraints without gold dispositions or reasons. Changed rubric or
+  calibration fingerprints require a fresh compatible evaluation baseline.
+- `data/review-rules.ja.yml`: generic framing already includes `本章では`, but
+  a candidate is not a diagnosis of an ambiguous actor. Adding every occurrence
+  of `確認` would also flag legitimate operational checks.
+
+The publisher's review workflow already requires neighboring context, faithful
+alternatives, individual decisions, and separate scopes. Its missing operational
+step is to record whether a targeted sentence is content guidance, an actual
+procedure, runtime behavior, or a learning objective before choosing its verb.
+
+## Proposed shared-criteria change
+
+Keep the existing sentence-role section and revise its introductory-ending row.
+Do not add a banned-word list. Suggested English instruction:
+
+> Keep useful subject and reading-order guidance, but separately assess its actor
+> and predicate. Distinguish the book explaining a subject from a reader checking
+> evidence and a program validating state. When the author requests explanatory
+> narration, prefer `説明します`, `示します`, or `比較します` for content guidance.
+> A useful sequence alone does not justify retaining `確認します`. Preserve a
+> genuine exercise, checking instruction, or runtime check with its supported
+> actor, target, conditions, and timing.
+
+Add a paragraph-level check for transitions among `説明します`, `確認します`,
+`理解します`, and related inflections. A reader's learning objective is valid
+when presented as an objective; it must not be treated as an operation performed
+by the book. Read neighboring sentences and table column roles before adding
+an actor. Do not repeat subjects where the context already identifies them.
+
+For actual checks, compare equally faithful alternatives such as `照合します`,
+`検査します`, `参照します`, or an explicit actor plus `確認します`. Use a more
+specific operation only when the source establishes it. A configuration review
+must not become automatic validation; a connection owner's shutdown check must
+not become only a developer's test. Do not turn an unknown result into confirmed
+completion or add a guarantee from naming a checking actor.
+
+Treat `説明`/`解説` as contextual choices: content guidance can use `説明`, while
+in-depth background or design discussion can use `解説`. Do not rename tool or
+Skill description data, formal titles, quotations, or identifiers for variety.
+The exact preference remains with the author and the book.
+
+## Proposed calibration cases
+
+Use original, compact fixtures instead of importing a manuscript or private
+review session. Include full paragraph context and explicit editorial constraints
+when the expected choice depends on the author's voice.
+
+| Case | Source and proposed revision | Expected judgment and purpose |
+| --- | --- | --- |
+| Content guidance revised | `本章では、依頼の受付と結果の返却を確認します。` -> `本章では、依頼の受付と結果の返却を説明します。` | Accept under an explicit author preference for explanatory narration; preserve both subjects. |
+| Ambiguous guidance retained | The same content-guidance source remains unchanged under that preference. | Reject the editorial decision; do not excuse it because its subjects are concrete. |
+| Paragraph viewpoint repaired | A paragraph begins with `本章では…説明します` and ends with a reader's `役割を理解します` / `仕組みを確認します`; revise to presenting roles and explaining mechanisms. | Accept when the paragraph is entirely a content guide; retain all subjects and reading order. |
+| Reader exercise retained | `この演習では、利用者が接続設定、依頼の送信、終了状態を順に確認します。` remains unchanged. | Accept: an explicit actor actually performs an exercise. Use this to narrow the current `ending-scope-guide-kept` example, retaining its historical identifier. |
+| User check retained | `利用者は、変更するファイルと内容を確認してから編集を承認します。` remains unchanged. | Accept: preserve actor, target, order, and approval. |
+| Runtime check made exposition | `実行側は、承認後にも対象の変更を検査します。` -> a sentence merely explaining changes to the reader. | Reject: runtime behavior was replaced with exposition. |
+| Owner responsibility made test | `接続を生成した側は、終了後の資源の状態を確認します。` -> only a developer checks shutdown during a test. | Reject: the connection owner's runtime responsibility was lost. |
+| Unsupported actor assignment | A check whose neighboring evidence cannot identify its performer is rewritten as an Agent's automatic check. | Needs-evidence: do not invent automatic execution or assign ownership. |
+
+Keep the legitimate keep cases. The change should reduce ambiguous guidance
+without rewarding mechanical replacement of every check. Adjust fixture counts,
+required axes, judge rubric, and evaluation documentation together. Do not
+compare the expanded calibration's scores directly with the old calibration.
+
+## Proposed skill changes
+
+Use pubkit as the single source of prose criteria. Add the following workflow
+step to its bundled `examples/skills/review-asciidoc-manuscript/SKILL.md` and the
+publisher's `review-japanese-technical-book/references/review-workflow.md`:
+
+1. For a targeted ending, classify the sentence's role before judging its verb.
+2. Read the complete paragraph and neighboring sentences; inspect table context
+   separately when it is outside the selected prose scope.
+3. Record the supported actor, target, condition, actual alternative, comparison,
+   and disposition. Do not derive keep from the presence of a concrete subject
+   or a useful reading sequence.
+4. Apply author preferences from the current project instructions. Leave factual
+   uncertainty unresolved instead of inventing an actor or mechanism.
+
+The publisher's `japanese-technical-writing/SKILL.md` only needs a routing note
+that paragraph viewpoint is assessed using the saved common criteria; do not
+copy the new criteria there. Its OSS prose style profile can point to the same
+criteria if needed. Book-specific AGENTS.md remains the owner of the exact
+`説明`/`解説` preference. Do not impose Orbit's wording on sibling books.
+
+Update the publisher-local skills as a separately scoped change. Do not use
+`skill upgrade` to replace locally customized skills or modify old review
+sessions during this work. Skill changes are not an installed gem release.
+
+## Recommended implementation and validation order
+
+1. Revise shared criteria and add/narrow calibration examples; align the judge
+   rubric and evaluation guide. Add focused regression assertions for prompt
+   delivery, contextual axes, and retained actual-check controls.
+2. Update the bundled and publisher-local workflow instructions with the role
+   classification step, keeping prose criteria in pubkit.
+3. Run `bundle exec rake test` with real MeCab/IPADIC, relevant skill tests,
+   reference checks, and `git diff --check`. Preserve old sessions and their
+   saved criteria. Tests prove plumbing and fixture integrity, not improved AI
+   proofreading.
+4. If AI evaluation is explicitly requested, fix the expanded calibration and
+   rubric first. Compare old/new criteria using that same setup and identical
+   agent/model settings. Record per-case judgments; distinguish ambiguity repair,
+   preservation failures, and needless changes to valid checks. Keep logs and
+   treat a small fixture set as diagnostics rather than a general ranking.
+5. Consider detector hints only after evaluating remaining missed cases and
+   review noise. A later hint must be advisory, cover supported inflections and
+   exclusions, preserve positions, and have MeCab/literal regression tests.
+   It must never authorize automatic replacements or semantic verification.
+
+The original research proposal did not authorize a version bump, publication,
+installed-skill upgrade, old-session mutation, new manuscript edits or external
+model invocation. The author subsequently requested the implementation and
+v1.2.2 release as separate steps. Old sessions and manuscript sources remain
+outside the release work.
+
+## Implementation validation (2026-10-12)
+
+- The full suite passed with Homebrew Ruby 4.0.7 and real MeCab/IPADIC:
+  247 tests, 3,625 assertions, no failures, errors or skips.
+- The bundled review skill and both affected publisher-local skill directories
+  passed skill-creator's structural validator. This validates skill structure,
+  not the quality of an agent's judgments.
+- Fixture integrity, explicit author constraints and unchanged valid-check
+  controls are covered. Shared criteria reach writing and all review scopes;
+  saved sessions retain their original criteria.
+- No external model evaluation was run. No measured AI proofreading improvement
+  or publication readiness is claimed.
+- At the source-update checkpoint, the installed gem remained v1.2.1 and no
+  version bump, publication, commit or push had been performed. The subsequent
+  author-authorized release targets v1.2.2.

data/docs/installation.md

@@ -66,7 +66,7 @@ git clone https://github.com/cybergarage/asciidoc-pubkit.git
 cd asciidoc-pubkit
 bundle install
 gem build asciidoc-pubkit.gemspec
-gem install ./asciidoc-pubkit-1.2.0.gem
+gem install ./asciidoc-pubkit-1.2.1.gem
 asciidoc-pubkit --version
 ```
 

data/docs/prose-evaluation.md

@@ -6,7 +6,7 @@ readability, and meaning preservation separate so that a clearer rewrite cannot
 hide a lost condition or invented fact.
 
 This guide describes the development checkout, including the
-`technical-prose-v3` corpus and 59 revision calibration pairs. The sentence-ending
+`technical-prose-v3` corpus and 77 revision calibration pairs. The sentence-ending
 criteria and twelve additional pairs, plus the flow guidance and four further
 pairs, are included in version 1.2.0.
 The evaluation runner is not an
@@ -45,7 +45,7 @@ of Japanese writing.
 | [prose_benchmark.ja.adoc](../test/fixtures/prose_benchmark.ja.adoc) | 26 paragraphs used as the actual AsciiDoc input |
 | [prose_benchmark.ja.json](../test/fixtures/prose_benchmark.ja.json) | Matching paragraph IDs and text, 11 annotated detector targets, and preservation checklists |
 | [prose_benchmark.yml](../test/fixtures/prose_benchmark.yml) | Fixed empty configuration that isolates the benchmark from discovered manuscript settings |
-| [prose_evaluation.ja.json](../test/fixtures/prose_evaluation.ja.json) | Detection examples and 59 manual revision pairs with expected `accept`, `reject`, or `needs-evidence` dispositions |
+| [prose_evaluation.ja.json](../test/fixtures/prose_evaluation.ja.json) | Detection examples and 77 manual revision pairs with expected `accept`, `reject`, or `needs-evidence` dispositions |
 
 The corpus includes framing such as `重要なのは`, metaphorical operations such
 as `地味に効く`, inflected and negative forms, and repeated endings. Controls
@@ -100,6 +100,15 @@ fresh AI baseline using the expanded calibration and rubric before comparing
 criteria. Normal tests check fixture integrity and prompt delivery, not whether
 an AI accepts or rejects each pair correctly.
 
+The version 1.2.1 terminology update adds eleven calibration pairs covering technical
+selection without a modality change, explicit author preferences, logical separation
+versus invented physical isolation, language independence versus partition, data
+partition, concrete workflow descriptions and legitimate library embedding. The
+optional judge receives each pair's `editorial_constraints` without its expected
+disposition or gold reason. These fixtures and deterministic plumbing tests do not
+establish improved model proofreading; an explicitly requested AI evaluation is
+required to measure that behavior.
+
 The version 1.2.0 `流れ` guidance adds four calibration pairs: a more specific
 information-transfer description, a clear operation with its condition retained,
 and rejected substitutions that invent lifecycle stages or remove a success
@@ -110,6 +119,17 @@ its three existing kinds; its scores do not measure the new `流れ` cue. The
 calibration fingerprint changes, so establish a fresh AI baseline before comparing
 rewrite quality. Normal tests do not evaluate an AI's editorial judgments.
 
+The version 1.2.2 explanatory-guidance update narrows the existing
+`ending-scope-guide-kept` case to an actual user exercise and adds seven pairs
+(77 total). They distinguish content guidance, an explicit author voice,
+paragraph viewpoint, user approval, runtime checks, connection ownership and
+unsupported automatic actors. The judge rubric and calibration fingerprints
+change, while the 26-paragraph detector corpus and rules remain unchanged.
+Establish a fresh compatible AI baseline before measuring the criteria change.
+Normal tests validate fixture integrity, prompt delivery and saved criteria;
+they do not establish improved AI proofreading. See the
+[research and proposal](explanatory-guidance-research.md) for the design rationale.
+
 ## What normal tests check
 
 Run the complete suite from the repository root with MeCab and UTF-8 IPADIC

data/docs/review-workflow.md

@@ -296,6 +296,23 @@ verify check the value against the session language. A non-Japanese language in
 `--lang`, `review.language`, or an explicit AsciiDoc `:lang:` attribute is rejected.
 An omitted `:lang:` attribute uses the selected review language.
 
+### Faithful terminology comparisons
+
+Preserve modality separately from wording: `選べます → 選択できます` retains
+capability, while `選べます → 選びます` asserts behavior. Apply author terminology
+preferences even when both expressions are understandable. Compare the strongest
+supported alternative with the same facts and conditions; rejecting invented
+physical isolation does not justify keeping vague separation wording. The saved
+shared criteria distinguish data partition, responsibility separation, independent
+implementation languages and concrete workflow integration.
+
+`組み込む` and its potential/negative inflections are advisory `weak-predicate`
+candidates in the packaged Japanese rules. They are not prohibited expressions or
+replacement instructions; named library embedding may be appropriate. Custom rules
+still replace the packaged rules. Review author-supplied concerns and paragraphs
+without matches as well. Existing sessions retain their saved rules and criteria;
+start a new scan to apply the updated guidance, preserving earlier evidence.
+
 ### Verify
 
 ```sh

data/docs/rules-and-coverage.md

@@ -142,7 +142,7 @@ reports analyzer changes instead of treating results from different dictionaries
 as directly comparable. Prompt generation uses saved evidence and does not need
 MeCab. Changed rules or dictionary settings require a new scan.
 
-Versions 1.1.0 and 1.2.0 use session schema 3, but sessions still require their exact tool version.
+Versions 1.1.0, 1.2.0 and 1.2.1 use session schema 3, but sessions still require their exact tool version.
 Sessions with a different schema or tool version cannot be loaded. Keep the original baseline for
 an ongoing review and finish it with the original version, or start a new review
 pass in a different directory:

data/docs/writing.md

@@ -27,6 +27,13 @@ A noun-phrase heading policy does not apply to body sentences. These examples
 are contextual decisions, not new detector terms or replacement rules. See
 [Sentence-ending criteria](../data/writing/ja/criteria.md#review-sentence-endings-by-their-role).
 
+Terminology comparison is independent of sentence function. A technical synonym
+can improve consistency while retaining the same capability or condition; honor
+explicit author preferences rather than keeping a plain verb just because it is
+understandable. Compare a faithful full explanation, not an unsupported stronger
+alternative or a shortened passage. See
+[Terminology and modality](../data/writing/ja/criteria.md#compare-terminology-independently-of-modality).
+
 The criteria also preserve the comparison axis, completed changes,
 current behavior, future plans, and the distinction between event dates and
 observation or report dates. An unclear state term does not authorize deleting
@@ -48,7 +55,7 @@ asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
 ```
 
 For example, `--lang en` exits with an unsupported-language error. No English
-review or writing criteria are shipped in 1.2.0.
+review or writing criteria are shipped in 1.2.1.
 
 For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
 paragraphs deliberately contain review candidates; its code block must remain

data/examples/skills/review-asciidoc-manuscript/SKILL.md

@@ -42,12 +42,26 @@ For each assigned scope:
    the baseline. For integrity failures, preserve evidence and report the blocker.
    Finish verification before scanning the next scope's current manuscript.
 
+Before judging a targeted sentence ending in prose or list text, classify its
+role using the saved common criteria: content guidance, an actual checking
+procedure, runtime behavior, or a learning objective. Read the whole paragraph
+and neighboring sentences; inspect table context separately when it is protected.
+Record the supported actor, target, conditions, faithful alternative and reason.
+A useful reading sequence alone is not a keep rationale. Follow the author's
+voice without inventing an actor or turning runtime responsibility into a test.
+
 Compare broad or everyday wording with a concrete alternative using the saved
 shared terminology criteria, even when the original is understandable. Keep
 records must explain the specific comparison, not merely summarize the passage.
 Reporting helpers may count explicit decisions but must not create keep decisions
 or inherit paragraph summaries. Missing comparisons remain pending.
 
+Compare the strongest supported alternative with the same facts and modality.
+Do not reject a requested technical synonym merely because it preserves meaning;
+apply the author's terminology preference. Rejecting an unsupported stronger
+alternative does not establish keep. Recheck a retained passage when its comparison
+changes the claim, omits source information, or fails to address the author's concern.
+
 Retain phase-end results because later scopes can legitimately make older
 sessions fail. For further corrections after another scope has changed, start a
 separate scoped pass and retain the prior evidence. Run the project's requested

data/lib/asciidoc_pubkit/session.rb

@@ -462,6 +462,7 @@ module AsciidocPubkit
         Record each reviewed #{unit} ID and each candidate ID with revise, keep, or needs-evidence and a reason grounded in that passage. For keep, identify the concrete referent, operation, condition, necessary distinction, or established terminology that justifies retaining it. A shared generic reason does not establish individual review. Appending a source quotation to a stock reason is still insufficient.
         For each candidate decision, identify its concrete role or claim, the evidence and source location, the direct wording considered, and why that alternative is better or why the original wording is necessary. For needs-evidence, name the missing support instead of inventing a role or revision. A quotation supports evidence but does not substitute for that explanation. For role metaphors such as 入口, apply the shared criteria even when a nearby identifier makes the referent clear.
         For broad or everyday wording, record a concrete alternative and a passage-specific comparison before choosing keep or revise. Apply the saved shared terminology criteria even when the original is understandable. A passage summary is not a wording comparison.
+        Compare the strongest faithful alternative with the same facts and modality. Same meaning alone does not justify keep when established technical terminology or the author's wording preference is better served. Rejecting an unsupported stronger alternative is not a comparison with a supported improvement. Assess concerns supplied by the author even when the detector emits no candidate for that wording.
         Reporting helpers may validate and count explicit assessments but must not manufacture keep decisions or inherit a paragraph summary as a candidate assessment. Missing or insufficient comparisons remain pending; they are not needs-evidence unless factual support is missing. Automatic decisions and zero pending counts cannot establish completion.
         Never infer revise or keep from whether the matched string survives, disappears, or changes. Do not bulk-assign keep to unchanged #{unit}s or remaining candidates. An unreviewed item stays pending; use needs-evidence only after review identifies missing evidence.
         Review #{unit}s without candidates against the shared criteria as well. For concerns outside the editable scope, report the location and a separate out-of-scope proposal; do not count protection as an editorial keep decision or edit protected content.

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '1.2.0'
+  VERSION = '1.2.2'
   class Error < StandardError; end
 
   def self.hash_text(text)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoc-pubkit
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.2
 platform: ruby
 authors:
 - CyberGarage
@@ -61,6 +61,7 @@ files:
 - docs/development.md
 - docs/document-commands.md
 - docs/english-review-research.md
+- docs/explanatory-guidance-research.md
 - docs/installation.md
 - docs/list-review.md
 - docs/outline-review.md