asciidoc-pubkit 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e36fd7643b859273dd775f683b1ff318ef8dfb241526a35bcff9c782498640df
-  data.tar.gz: f9dc7e9f69a5215f533caf0a04956db74d4c1bfe83e521de9be3108903a542f4
+  metadata.gz: 344dfb065e1bc2a69918b59ba37caa6a4857f89a8e8b52aab65614ad0f3d0cb4
+  data.tar.gz: 0ab6f311b266bb760e7b06ee614fe8e3785483f42117e25290d50755f94ac17a
 SHA512:
-  metadata.gz: 1be8e3e0c36fe561ed6bdf7c02140dafcfc8cdd5e6db36f3e8d2e0f8a4f201ceb622c5ed2447ae829c13d8242b8937815468b06eeed02495f501bee6b1c58ccf
-  data.tar.gz: '089d16921b8fcfd50a78e284262f6e415c6399eee0ee18bb17b36755bdcaa3158a73467f673443adf1ebede7c56246f3716cd34f6e8f578795aca8b7b39e3661'
+  metadata.gz: 5180830a2ecc63aca2a4e3046ad9fed14a0dd5195c043a6af995f228082d79efadf3aaa19c89373b45d55e84dbbdd458ad7f89b98db4f25198d5b68bb9667681
+  data.tar.gz: 22ef17dde95619bb6c52fd99848e6787d5acfa702fef72cb69a0bb943753e93835b277a78660f7d121ec09506dc2caa7218fae77564d7ffa406485765c590157

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## 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

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.1 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.1.
+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.1.
 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
-70 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,
@@ -168,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.1. 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/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
@@ -275,7 +276,7 @@ otherwise compare the wording independently of its sentence role before retainin
 
 | 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, 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. |
@@ -309,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/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 70 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 70 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
@@ -119,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/examples/skills/review-asciidoc-manuscript/SKILL.md

@@ -42,6 +42,14 @@ 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.

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '1.2.1'
+  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.1
+  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