asciidoc-pubkit 0.8.4 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f629e73e42aa273d3f13a77a917208bf9d54a7c53f024c89c0f7f8fae596934
-  data.tar.gz: fdfd437f9a8c7735b873b3df5da5c55662be58a7871e5c3017f360f09539c382
+  metadata.gz: bcbb2a3c913ace085eb70388740dfc506fefd0ef064380c58e0ebbab63b422a8
+  data.tar.gz: 7b643916c2b5c19f2264541f9e8660d212e7a351a1de10142087e4437b527f56
 SHA512:
-  metadata.gz: d02a86fc684bed05d233025281de87ecd8adf45ed15ae72b57b6e15c12d3572df48b3697294768a3aab3de5e40e1d02ea0828c5a39efd6c3b8f4d68c75f3f2ee
-  data.tar.gz: 54d8f0862dc0b45f78184613e12098569486541378b0fd72b2e218b0daf94846c3513536620c5a5a6a90197d8f07ef6e1526b153523e3d87e2867dd1c15ac58d
+  metadata.gz: 3cbda445b71d34817dfb51f64c49665106ae471ad98c0af3995697475f578fb658bdf2abc9e1894538a01d1e6e18b5d6fe850a9c818d868d8c2ad2663dd29598
+  data.tar.gz: dd89673d6281bc418a127dcd14ab7273e4919d677a84ef38b3b9a431ade81aa3d7ff8615b3bcfeaeeebe4de9e4016e157cb7d43065dbb4d511ee19bdd3f48341

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.8.5 — 2026-10-02
+
+- Refine role-metaphor guidance for 入口: consider the actual creation, invocation,
+  configuration, reference, learning, or entry-point role even with a clear
+  referent. Require decision-specific evidence and evaluated alternatives rather
+  than stock reasons with appended quotations; keep quality checks advisory.
+- Add 入口 as a heading topic candidate while preserving generated IDs and edit
+  scopes. Clarify review integrity failure handling and limits of reports about
+  excluded lists and other unsupplied content.
+
+- Add contextual Japanese revision examples for extension terminology, exposed
+  interfaces, layered structures, process tracking, missed events, processing,
+  and concise capabilities or obligations. Preserve actors, modality, ordering,
+  visibility, counts, and structural distinctions when choosing alternatives.
+- Add extension and indirect-expression candidates, reuse existing tracking
+  predicates, and extend configured use/handling potential forms and selected
+  operation lemmas with literal-mode surfaces.
+
 ## 0.8.4 — 2026-10-02
 
 - Require passage-specific review decisions in prose and heading prompts instead

data/README.md

@@ -7,7 +7,7 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.8.4 provides shared Japanese technical writing criteria, an authoring
+Version 0.8.5 provides shared Japanese technical writing criteria, an authoring
 prompt, separate prose and heading review prompts, manuscript scoring, and
 baseline verification for edited manuscripts, plus explicit prose-only mechanical
 replacements using a limited prh-format rule set.
@@ -16,7 +16,7 @@ Japanese text is retained in manuscript excerpts, rule dictionaries, and fixture
 
 ## Available features
 
-The following commands are available in version 0.8.4.
+The following commands are available in version 0.8.5.
 
 | Feature | Commands | Behavior |
 | --- | --- | --- |
@@ -107,7 +107,7 @@ Add the gem to your project's `Gemfile` to manage its version with Bundler:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'asciidoc-pubkit', '~> 0.8.4'
+gem 'asciidoc-pubkit', '~> 0.8.5'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -129,7 +129,7 @@ git clone https://github.com/cybergarage/asciidoc-pubkit.git
 cd asciidoc-pubkit
 bundle install
 gem build asciidoc-pubkit.gemspec
-gem install ./asciidoc-pubkit-0.8.4.gem
+gem install ./asciidoc-pubkit-0.8.5.gem
 asciidoc-pubkit --version
 ```
 
@@ -153,7 +153,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 0.8.4.
+review or writing criteria are shipped in 0.8.5.
 
 For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
 paragraphs deliberately contain review candidates; its code block must remain
@@ -624,6 +624,13 @@ verification. They request separate reports for mechanical preservation,
 candidate decisions, and paragraph or heading quality review, with counts and
 unresolved items. Protected-scope concerns are separate proposals, not evidence
 of editorial approval. Pending items make the review incomplete.
+Version 0.8.5 further requires an individual role or claim, located
+evidence, a considered direct alternative, and the rationale for each candidate
+decision. A stock reason with an appended quotation is insufficient. For `入口`,
+the shared criteria ask whether creation, invocation, configuration, reference,
+or a learning role can be stated directly even when the referent is clear.
+Remaining role metaphors must be checked against those individual decisions.
+
 These are reviewer instructions: the gem does not validate a decision ledger
 or prove that an AI or human followed the instructions. Keep session metadata
 and baseline snapshots immutable; format only authorized manuscript spans.
@@ -1022,6 +1029,17 @@ These are candidates for contextual review, not banned expressions. A necessary
 condition, uncertainty, or distinction must survive a revision; a redundant
 disclaimer can instead be removed or folded into a more precise main claim.
 
+Version 0.8.5 extends the existing `入口` question and shared criteria
+without adding another prose matcher. A known referent alone does not justify
+vague role wording; direct alternatives are evaluated against the actual
+operation, conditions, and technical usage. The heading `heading-vague-topic`
+rule also includes `入口`; proposed title changes must preserve generated IDs
+or be reported for a separate authorized migration. Lists remain excluded and
+are not included in prose or heading body evidence. Reports about outside-scope
+concerns cover only content actually inspected, not unreviewed excluded blocks.
+If baseline or artifact integrity fails, preserve the evidence and stop editing;
+never update snapshot hashes or replace the baseline to claim a successful review.
+
 Version 0.8.3 also includes scoped candidates such as `構築入口`,
 `エラーを回収する`, `ツールを呼ぶ`, `したりできます`, and `設計の肝`.
 These additions use the exact surfaces listed in the YAML in both modes;
@@ -1044,6 +1062,16 @@ precedence. `木全体` is an explicit contextual phrase in both modes because
 IPADIC can parse `木全` as a surname; this narrowly addresses that segmentation
 case without treating all names or compounds containing `木` as trees.
 
+Version 0.8.5 additionally reviews `拡張点`, `使えます`, `積み重なります`,
+`開放しています`, `見落とします`, `扱えます`, `使っています`, and selected indirect
+phrases. Existing tracking rules cover `追えます`. MeCab uses configured lemmas
+for use, potential handling, accumulation, oversight, and sahen opening;
+literal mode uses the listed surfaces. The shared examples distinguish an
+extension point from its mechanism, layers from a stack, system detection from
+human oversight, and processing from control. Revisions preserve actors,
+capabilities and obligations, sequence, visibility, counts, and distribution.
+These additions need a fresh scan and are contextual review guidance.
+
 Metaphorical-operation candidates include limited exact surfaces of
 `地味に効く`, `静かに壊れる`, `時間を溶かす`, and `側に倒す`, including selected polite,
 past, and connective forms listed in the packaged YAML. They use contextual
@@ -1096,12 +1124,12 @@ 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.
 
-Sessions from earlier tool versions are not compatible with 0.8.4 (session schema 2). Keep the original baseline for
+Sessions from earlier tool versions are not compatible with 0.8.5 (session schema 2). 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:
 
 ```sh
-asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.4
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.5
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship

data/data/heading-rules.ja.yml

@@ -12,7 +12,8 @@ terms:
     terms:
     - いろいろ
     - さまざまなこと
-    question: 'Check whether the heading identifies the actual subject, operation or comparison. Use the section as evidence; do not invent missing specificity.'
+    - 入口
+    question: 'Check whether the heading identifies the actual subject, operation or comparison. Use the section as evidence; apply the shared role-metaphor criteria to 入口 and preserve section IDs. Do not invent missing specificity.'
 fixed_titles:
 - はじめに
 - 本書の構成

data/data/review-rules.ja.yml

@@ -34,14 +34,19 @@ terms:
     # Review context before choosing a katakana technical term.
     - 木
     - 余白
-    question: Identify the concrete referent, components, or measurable work. Keep
+    question: Identify the concrete referent, components, role, or measurable work.
+      For 入口, apply the shared role-metaphor criteria; a clear referent alone is
+      not a sufficient reason to keep vague operation wording. Keep
       established technical meanings. For 木 and 余白, consider a context-appropriate
       katakana term (such as ツリー or マージン) only when it names the intended concept.
   weak-predicate:
     terms:
     # Use, interpretation, and understanding (literal-mode surfaces).
     - 利用します
+    - 使えます
+    - 使っています
     - 扱います
+    - 扱えます
     - 扱いません
     - 意味しません
     - 把握します
@@ -58,6 +63,7 @@ terms:
     - 調べられます
     - 確かめます
     - 探します
+    - 見落とします
     - 追えます
     # Inspect retrieval, interpretation, and invocation for any object.
     - 呼ぶ
@@ -75,6 +81,8 @@ terms:
     - 作ります
     - 組み立てられます
     - 組み合わせます
+    - 積み重なります
+    - 開放しています
     - 成り立たせています
     # Organization, comparison, and selection.
     - 整理します
@@ -153,6 +161,7 @@ terms:
     - エラーを回収する
     - エラーを回収します
     - 介入パターン
+    - 拡張点
     # Object-specific everyday verbs, not general bans on these verbs.
     - ツールを呼ぶ
     - ツールを呼びます
@@ -166,6 +175,10 @@ terms:
     # Indirect capabilities and prerequisites; preserve their modality.
     - したりできます
     - することが前提です
+    # Preserve capability, distributed structure, and the responsible actor.
+    - 切り替えで扱えます
+    - 分かれて現れます
+    - 担保しなければなりません
     # Compressed noun relationships; suggestions are not automatic replacements.
     - 明示選択
     - 欠落理由
@@ -218,6 +231,14 @@ terms:
 verbs:
   扱う:
   - 扱う
+  - 扱える
+  使う:
+  - 使う
+  - 使える
+  積み重なる:
+  - 積み重なる
+  見落とす:
+  - 見落とす
   示す:
   - 示す
   変わる:
@@ -321,6 +342,7 @@ sahen:
 - 解消
 - 混同
 - 回収
+- 開放
 negative_only:
 - 到達する
 - 意味する

data/data/writing/ja/criteria.md

@@ -34,7 +34,9 @@ adjacent sentences.
 
 ## Replace abstraction with the thing being discussed
 
-Abstract terms are valid when their referent is stated. Inspect terms such as:
+Identify both the referent and its role before retaining an abstract term.
+A named API, file, or command can make the referent recoverable while leaving
+its operation vague. Inspect terms such as:
 
 | Term | What must be identifiable |
 | --- | --- |
@@ -49,6 +51,33 @@ Do not improve a sentence by replacing one abstraction with another. For
 example, changing `費用` to `コスト` says nothing unless the sentence identifies
 what increases.
 
+For role metaphors such as `入口`, check whether naming the actual operation or
+relationship gives the reader more useful information, even when the referent
+is already clear. Consider these alternatives only when evidence supports them:
+
+| Intended role of 入口 | More direct wording |
+| --- | --- |
+| Object creation | 生成API・生成メソッド, or state what the method creates |
+| Invocation or external access | 呼び出しAPI・アクセス経路, or name the call and its operation |
+| Configuration or prompt changes | 設定項目・上書きメソッド・コールバック・変更手段, preserving the changed scope |
+| Command use | Name the command and the action it performs |
+| Documentation or test references | 参照先・確認対象, or state what the document explains or test checks |
+| Learning introduction | 導入例・理解する手がかり, supported by the example's actual content |
+| Actual execution entry point | エントリポイント when that is the established technical role |
+
+For example, `実行基盤を作る入口はcreate()です` can become
+`実行基盤は生成メソッドcreate()で作ります`; `利用側の入口はinstallです` can
+become `インストールするコマンドはinstallです`. Keep asynchronous behavior,
+inputs, conditions, and other facts from the surrounding passage.
+Do not replace every `入口` with `エントリポイント`, or introduce an API,
+mechanism, or stronger guarantee that the source does not establish. Preserve
+negation and scope: a catalog listing does not imply an execution method exists.
+Distinguish a public option or return field from internal state before describing
+a change mechanism. Literal entrances and clearly established technical usage
+can remain. For keep, explain the role and why retaining the wording serves the
+reader better than the considered direct alternative; naming its referent alone
+or appending the original sentence to a generic reason is insufficient.
+
 ## Give weak predicates a concrete action or consequence
 
 Predicates such as `利用します`, `決めます`, `示します`, `扱います`, `整理します`,
@@ -76,11 +105,25 @@ For everyday verbs, identify the operation before choosing terminology:
 | 設定を書く・設定を書きます | 設定を記述する・定義する for authoring a definition; 設定する for actually configuring something |
 | 値を拾う | 取得する for retrieval; 抽出する for selection from existing data |
 | 切り出す合図です | 切り出す目安です for a judgment criterion; シグナルです only for an actual signal |
+| インタフェースから使えます | 利用できます when describing availability through the interface; retain the actor and capability |
+| 拡張機構が積み重なります | 階層化されています only for established layers; スタックを構成しています only for an actual stack and its ordering |
+| 拡張点として開放しています | 提供しています for offering an extension facility; 公開しています for exposing access, preserving any access restrictions |
+| 自動継続を途中で切らずに一巡を追えます | 追跡できます・トレースできます when following the sequence; preserve the complete cycle and uninterrupted continuation |
+| 再試行を見落とします | 検知漏れが生じます・捕捉漏れが発生します for a system's detection failure; 見落とすリスクがあります for a human's possible oversight |
+| 差分を隠しすぎずに扱えます | 処理できます for processing; 制御できます only when control is available, preserving how much difference remains visible |
+| 通知文に使っています | 用いられています when the use is the focus and the actor is recoverable; retain active voice when who uses it matters |
 
 A familiar verb is not wrong merely because it is simple. Prefer the most direct
 accurate verb; do not introduce jargon or claim parsing, execution, or a state
 change that the evidence does not establish.
 
+Layering and a stack are different structural claims. Do not infer either from
+an accumulation metaphor alone. Tracking is more specific than confirmation;
+retain ordering and continuity instead of shortening it to `確認できます`.
+Distinguish an observed detection failure from a risk of human oversight: do not
+turn a definite failure into a possibility or assign human observation to a
+system. Active and passive voice must preserve the same actor and responsibility.
+
 Do not choose a more impressive synonym merely to vary sentence endings. Keep
 the technically correct verb when it names the real operation.
 
@@ -175,6 +218,16 @@ Inspect indirect predicates and author-centered emphasis as well:
 
 - Simplify `無効化したりできます` to `無効化できます` when it describes a single
   capability. Preserve `たり` when it marks a meaningful non-exhaustive list.
+- Simplify `切り替えで扱えます` to `切り替えられます` when switching is the
+  capability itself. Preserve the subject, alternatives, and any separate
+  operation enabled by switching.
+- For `三点に分かれて現れます`, identify what the three points represent. Use
+  `3か所に分散します` for distributed locations or `3つの要素として定義されます`
+  for defined elements only when that structure is established. Keep the count,
+  separation, and relationships; `現れます` alone loses structural information.
+- Simplify `担保しなければなりません` to `担保が必要です` only when the guaranteed
+  property, responsible actor, and requirement remain explicit. A noun phrase
+  must not hide who must establish the guarantee or weaken an obligation.
 - For `提供することが前提です`, identify whose prerequisite or assumption is
   stated. Use `提供する必要があります` only when the source establishes an actual
   requirement; do not turn an assumption into an obligation.
@@ -218,11 +271,17 @@ Review unusual translations against the actual concept:
 | Wording to inspect | Context-dependent terminology |
 | --- | --- |
 | 木 | ツリー when referring to the data structure; keep literal trees and established mathematical usage |
+| 拡張点 | 拡張ポイント for the specific extension location or interface; 拡張機構 for the broader mechanism only when that is the intended referent |
 | 構築入口 | ビルドのエントリポイント only when the entry point starts a build, not object construction or initialization |
 | 実装の読解 | コードリーディング for reading code; 実装の解析 when analysis is the actual task |
 | エラーを回収する | エラーを捕捉する for catching; ハンドリングする for handling; preserve aggregation or collection when that is the behavior |
 | 介入パターン | フックパターン only when a hook mechanism is established, not arbitrary human intervention |
 
+An extension point and an extension mechanism can denote different scopes.
+Keep `拡張点` when it is the project's established term and its referent is clear;
+choose terminology for the actual interface or mechanism rather than replacing
+all occurrences with a broader term.
+
 These alternatives are not interchangeable replacements. Confirm the operation
 and the domain's established usage from code, the glossary, or primary
 documentation; record uncertainty rather than inventing a mechanism.

data/data/writing/ja/headings.md

@@ -17,6 +17,13 @@ Preserve conditions, negation, technical distinctions and exact terminology.
 If supporting body text is missing or insufficient, record needs-evidence.
 A table of contents alone cannot establish agreement with the section body.
 
+For a title such as `手動圧縮の入口` or `画像・分類モデルへの入口`, apply the
+shared role-metaphor criteria to the section evidence. Consider `起動方法` or
+`呼び出しAPI` only when that is what the body explains. Naming a subject does
+not by itself explain the operation. If a better title would change a generated
+section ID, record the proposed title and ID concern for a separate authorized
+migration rather than changing anchors or keeping it for stylistic reasons.
+
 ## Compare headings with the same role
 
 Read the complete outline and compare parent, sibling and child headings.

data/lib/asciidoc_pubkit/session.rb

@@ -381,11 +381,13 @@ module AsciidocPubkit
         ## Review decisions and completion
 
         Keep manifest.json, document.json, findings.json, and every baseline/ snapshot immutable. Restrict editing and formatting tools to the authorized source spans; never run them over the session directory.
-        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.
+        Check mechanical preservation and baseline integrity with this session before editing and at completion. If a baseline or artifact integrity check fails, stop editing, preserve the evidence, and report the failure. Do not repair or overwrite snapshots, update their hashes, or replace the session to turn a failed check into a successful report; a fresh scan cannot prove preservation against the original baseline.
+        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.
         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.
         #{mode == 'revise' ? 'Compare the original and edited passages, check both information loss and unsupported additions, and reconcile each recorded decision with the actual diff. After verification, individually inspect newly detected or remaining candidates; retain the original candidate IDs in the review record.' : 'Compare each proposed revision with the original passage for information loss and unsupported additions. A revise decision means a proposed revision, not an applied edit.'}
-        Report mechanical preservation, candidate decisions, and #{unit}-level quality review separately. State selected and reviewed #{unit} counts, candidate decision counts, pending items, needs-evidence items, out-of-scope concerns, and evidence used. If any selected item or candidate remains pending, report the review as incomplete.
+        Report mechanical preservation, candidate decisions, and #{unit}-level quality review separately. State selected and reviewed #{unit} counts, candidate decision counts, pending items, needs-evidence items, out-of-scope concerns, and evidence used. Recheck retained role metaphors by their actual roles and cite the individual decisions; listing remaining words is not enough. Out-of-scope concerns cover only evidence actually inspected; the supplied prose/body context omits lists and other excluded blocks, so do not claim those were reviewed. If any selected item or candidate remains pending, report the review as incomplete.
         Mechanical verification does not read or validate these decision records. Its passed result and candidate counts do not establish review completion or writing quality; meaning_verified remains false. Do not claim semantic correctness from those checks.
       TEXT
     end

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '0.8.4'
+  VERSION = '0.8.5'
   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: 0.8.4
+  version: 0.8.5
 platform: ruby
 authors:
 - CyberGarage