asciidoc-pubkit 0.8.4 → 0.8.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f629e73e42aa273d3f13a77a917208bf9d54a7c53f024c89c0f7f8fae596934
-  data.tar.gz: fdfd437f9a8c7735b873b3df5da5c55662be58a7871e5c3017f360f09539c382
+  metadata.gz: e1fb57dff066c28a30d6205ad30ff8c5cd1a89fc27c35ec8379e9c80354843ae
+  data.tar.gz: 9431768603df5a8191ba93b0bc5773ad188050e06304e6f0f35272bbe132ef51
 SHA512:
-  metadata.gz: d02a86fc684bed05d233025281de87ecd8adf45ed15ae72b57b6e15c12d3572df48b3697294768a3aab3de5e40e1d02ea0828c5a39efd6c3b8f4d68c75f3f2ee
-  data.tar.gz: 54d8f0862dc0b45f78184613e12098569486541378b0fd72b2e218b0daf94846c3513536620c5a5a6a90197d8f07ef6e1526b153523e3d87e2867dd1c15ac58d
+  metadata.gz: 901984c71c8178ba62738e21ec67cb5585ebe72719ef06c03b38585c5ad7d0961a9fe4da78c47d1612e9c339d6170bee9a060ea4cf2cf68e9301ae4b80bb96ac
+  data.tar.gz: 70570e253745de217ba1d4eb2c5447a7a1dba2f72e3d1f5f1abb40787d54c996fa9dca3072bb190071a459346146200e5744e9eb5fa72f4410c9dd314af71333

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.8.6 — 2026-10-02
+
+- Add separate `review scan --scope lists` sessions for source-mapped single-line
+  outline list text. Preserve markers, structure, inline tokens, and other scopes;
+  report unsupported or reused-source items as coverage notices.
+- Add opt-in `--preserve-heading-ids` for heading scans. Save exact old-ID anchor
+  permissions and verify only those additions immediately before their selected
+  headings while retaining section IDs, structure, and protected body content.
+- Advance sessions to schema 3; retain prior baselines and finish
+  ongoing reviews with their original tool and schema.
+
+## 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,8 +7,8 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.8.4 provides shared Japanese technical writing criteria, an authoring
-prompt, separate prose and heading review prompts, manuscript scoring, and
+Version 0.8.6 provides shared Japanese technical writing criteria, an authoring
+prompt, separate prose, heading, and list review prompts, manuscript scoring, and
 baseline verification for edited manuscripts, plus explicit prose-only mechanical
 replacements using a limited prh-format rule set.
 The CLI, diagnostics, documentation, and generated instructions are in English.
@@ -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.6.
 
 | Feature | Commands | Behavior |
 | --- | --- | --- |
@@ -24,6 +24,7 @@ The following commands are available in version 0.8.4.
 | [Replacement preview](#prose-replacements) | `replace check`, `replace diff` | Report mechanical replacement candidates or preview a diff for mapped running prose; preserve source files |
 | [Replacement application](#prose-replacements) | `replace apply` | Apply author-supplied rules after checking protected content and document structure; no MeCab or AI required |
 | [Prose review](#review-workflow) | `review scan` | Collect mapped Japanese running prose and contextual review candidates with MeCab/IPADIC by default |
+| [List review](#list-review) | `review scan --scope lists` | Review mapped single-line list text in a separate session |
 | [Heading review](#heading-review) | `review scan --scope headings` | Collect editable section titles separately, retaining the outline and read-only body evidence |
 | [Review prompts](#prompt) | `review prompt` | Generate one Markdown prompt from a saved session for review and editing by an external reviewer |
 | [Baseline verification](#verify) | `review verify` | Check edited sources against a saved baseline for mechanical preservation; meaning is not verified |
@@ -107,7 +108,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.6'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -129,7 +130,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.6.gem
 asciidoc-pubkit --version
 ```
 
@@ -153,7 +154,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.6.
 
 For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
 paragraphs deliberately contain review candidates; its code block must remain
@@ -520,8 +521,9 @@ are frozen into the session; scan again after changing them.
 
 ### Heading review
 
-Review headings and prose in separate sessions. The default scan scope remains
-`prose`; `--scope headings` selects section titles. There is no combined scope.
+Review headings, prose, and list text in separate sessions. The default scan scope
+remains `prose`; `--scope headings` selects section titles and `--scope lists` selects
+supported list text. There is no combined scope.
 Default output directories are `.pubkit/review` for prose and `.pubkit/headings`
 for headings, so separate scans do not replace each other by default.
 The scope is saved at scan time; `prompt` and `verify` use that saved scope.
@@ -564,12 +566,25 @@ and converted inline titles and physical title lines reused by multiple includes
 Unresolved section titles receive coverage notices. Verification permits only selected title text changes while
 protecting the body, title markers, hierarchy, order, section IDs, references,
 attributes, includes and other protected content. A title-derived section ID
-change fails verification. Establish stable explicit IDs before scanning when
-needed; this tool does not add IDs or migrate references. Numeric title changes
+change fails verification. To permit limited ID preservation, scan with
+`--scope headings --preserve-heading-ids`. Eligible generated headings then save
+an exact `permitted_id_anchor` in their metadata. A reviewer may insert only that
+anchor immediately before its selected heading, for example:
+
+```adoc
+[#_手動圧縮の入口]
+== 手動圧縮と拡張からの起動
+```
+
+Verification allows this exact addition while requiring the same section ID,
+hierarchy, order, and protected body. Existing explicit anchors remain protected;
+other anchors and reference migrations are outside this permission. Without the
+flag, only title text is editable. Scan and prompt never insert anchors or rewrite
+manuscripts. Numeric title changes
 are manual-review notices, and remaining candidates do not fail verification.
 `meaning_verified` remains `false`.
 
-The session schema is now 2. Earlier sessions must be recreated; preserve or
+Version 0.8.6 uses session schema 3. Earlier sessions must be recreated; preserve or
 finish an ongoing review with its original tool before establishing a new baseline.
 `review score` continues to support prose only and rejects `--scope`.
 
@@ -624,6 +639,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 +1044,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 +1077,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 +1139,13 @@ 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
+Version 0.8.6 uses session schema 3; version 0.8.5 uses schema 2.
+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:
 
 ```sh
-asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.4
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.6
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship
@@ -1119,6 +1163,33 @@ unambiguously, the paragraph is skipped with a coverage notice. Columns are
 one-based Unicode character positions, not byte offsets or display widths.
 An empty findings array does not establish full coverage or good prose.
 
+## List review
+
+Use a separate session to review list descriptions, including reference-list text:
+
+```sh
+asciidoc-pubkit review scan book.adoc --scope lists --output .pubkit/lists
+asciidoc-pubkit review prompt .pubkit/lists --output lists-review.md
+asciidoc-pubkit review verify .pubkit/lists
+```
+
+The default output directory is `.pubkit/lists`. This scope reuses prose rules,
+glossary, style, analyzer, and shared writing criteria. It does not include running
+prose or edit headings. Each selected item appears once with heading context;
+read additional evidence separately when its technical role cannot be established.
+
+Only exact source-mapped, single-line simple unordered or ordered item text is
+editable, including supported nested outline lists. Multiline, description,
+checklist, compound, ambiguous, and reused-source items remain protected with
+coverage notices. List markers, nesting, structure, links, and other inline tokens
+remain protected. Candidate columns include the source marker and indentation.
+Session JSON retains the `paragraphs` and `paragraph_id` keys, with
+`kind: list-item` and source `column`, `prefix`, and `suffix` metadata.
+
+Default prose scanning, scoring, and mechanical replacement keep their existing
+prose scope. Heading body evidence continues to omit lists. A successful verify
+checks preservation and does not establish editorial completion.
+
 ## Development
 
 ```sh

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,14 @@ 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, use the exact permitted_id_anchor only when the saved session explicitly
+authorizes it. Otherwise record the proposed title and ID concern for separate
+authorized preservation. Protection does not justify an editorial keep decision.
+
 ## Compare headings with the same role
 
 Read the complete outline and compare parent, sibling and child headings.

data/lib/asciidoc_pubkit/cli.rb

@@ -8,7 +8,7 @@ module AsciidocPubkit
       Commands:
         writing criteria      Print the shared Japanese prose criteria
         writing prompt        Generate a Japanese technical writing prompt
-        review scan FILE       Collect Japanese prose or headings and review candidates
+        review scan FILE       Collect Japanese prose, headings, or list text and review candidates
         review score FILE      Score Japanese prose; optionally use a local AI CLI
         review prompt SESSION  Generate an English review prompt with Japanese source excerpts
         review verify SESSION  Compare edited sources with the saved baseline
@@ -45,7 +45,7 @@ module AsciidocPubkit
       parser = OptionParser.new do |opts|
         input_name = group == 'writing' ? '' : ((group == 'replace' || %w[scan score].include?(command)) ? ' FILE' : ' SESSION')
         opts.banner = "Usage: asciidoc-pubkit #{group} #{command} [options]#{input_name}"
-        opts.on('-o', '--output PATH', group == 'review' && command == 'scan' ? 'New session directory (default: .pubkit/review for prose, .pubkit/headings for headings)' : 'New output file (default: standard output)') { |v| options[:output] = v }
+        opts.on('-o', '--output PATH', group == 'review' && command == 'scan' ? 'New session directory (default: .pubkit/review, .pubkit/headings, or .pubkit/lists)' : 'New output file (default: standard output)') { |v| options[:output] = v }
         opts.on('--lang LANG', 'Language (ja only in this release)') { |v| options[:language] = v }
         if group == 'replace'
           opts.on('--rules FILE', 'Required prh-format replacement rules (limited compatibility)') { |v| options[:rules] = v }
@@ -54,7 +54,8 @@ module AsciidocPubkit
           opts.on('--only FILE', 'Select one included file') { |v| options[:only] = v }
         elsif group == 'review' && %w[scan score].include?(command)
           if command == 'scan'
-            opts.on('--scope SCOPE', 'prose (default) or headings; separate review sessions') { |v| options[:scope] = v }
+            opts.on('--scope SCOPE', 'prose (default), headings, or lists; separate review sessions') { |v| options[:scope] = v }
+            opts.on('--preserve-heading-ids', 'Allow exact old-ID anchors before eligible headings') { options[:preserve_heading_ids] = true }
             opts.on('--heading-rules FILE', 'Replace default heading rules with a YAML rule set') { |v| options[:heading_rules] = v }
             opts.on('-y', '--yes', 'Answer yes to replacement confirmation') { options[:yes] = true }
             opts.on('--no-input', 'Never prompt; fail on existing output unless --yes') { options[:no_input] = true }
@@ -128,6 +129,8 @@ module AsciidocPubkit
         end
         if result['scope'] == 'headings'
           out.puts "Scanned #{result['headings']} headings; found #{result['findings']} review candidates."
+        elsif result['scope'] == 'lists'
+          out.puts "Scanned #{result['paragraphs']} list items; found #{result['findings']} review candidates."
         else
           out.puts "Scanned #{result['paragraphs']} paragraphs; found #{result['findings']} review candidates."
         end

data/lib/asciidoc_pubkit/document.rb

@@ -64,6 +64,15 @@ module AsciidocPubkit
           true
         end
         nodes.each { |node| collect(node) }
+        if scope == 'lists'
+          reused = @paragraphs.group_by { |p| [p['file'], p['line']] }.select { |_, group| group.length > 1 }
+          @paragraphs.reject! do |paragraph|
+            next false unless reused.key?([paragraph['file'], paragraph['line']])
+            @coverage << { 'context' => 'list_item', 'file' => paragraph['file'], 'line' => paragraph['line'],
+                           'reason' => 'The source list item is reused and cannot be edited independently.' }
+            true
+          end
+        end
       ensure
         Asciidoctor::LoggerManager.logger = previous_logger
       end
@@ -110,14 +119,80 @@ module AsciidocPubkit
         @coverage << { 'context' => 'heading', 'file' => path, 'line' => line, 'reason' => 'Excluded by configuration.' }
         return
       end
+      section_id = node.id
+      generated = section_id && !node.attributes.key?('id')
+      anchor = if @settings['preserve_heading_ids'] && generated && section_id.match?(/\A[\p{L}\p{N}_.:-]+\z/)
+                 "[##{section_id}]"
+               end
       @headings << { 'id' => AsciidocPubkit.hash_text([path, line, match[2]].join("\0"))[0, 16],
                      'index' => index, 'parent_index' => parent_index,
                      'file' => path, 'line' => line, 'column' => match[1].length + 1,
                      'prefix' => match[1], 'suffix' => match[3], 'level' => node.level,
-                     'section_id' => node.id, 'text' => match[2] }
+                     'section_id' => section_id, 'id_generated' => !!generated, 'permitted_id_anchor' => anchor, 'text' => match[2] }
+    end
+
+    def collect_list_item(node)
+      cursor = node.source_location
+      path, line = cursor && [cursor.file, cursor.lineno]
+      parent = node.parent
+      supported = %i[ulist olist].include?(parent.context)
+      while parent
+        supported = false if %i[quote verse table listing literal pass dlist colist].include?(parent.context)
+        parent = parent.parent
+      end
+      # ListItem#text applies substitutions; read through the public subs API.
+      original_subs = node.subs.dup
+      begin
+        node.subs.clear
+        text = node.text
+      ensure
+        node.subs.replace(original_subs)
+      end
+      raw = path && @source_lines[path] && @source_lines[path][line - 1]
+      pattern = node.marker && /\A([ \t]*#{Regexp.escape(node.marker)}[ \t]+)(.*?)([ \t]*)\z/
+      match = raw && pattern && raw.match(pattern)
+      # Include boundaries can leave the cursor on the include directive.
+      # Recover a unique physical span; repeated use is rejected after collection.
+      if supported && node.simple? && text && !text.include?("\n") && pattern && (!match || match[2] != text)
+        candidates = @source_lines.flat_map do |source_path, lines|
+          lines.each_with_index.filter_map do |source_line, offset|
+            candidate = source_line.match(pattern)
+            [source_path, offset + 1, candidate] if candidate && candidate[2] == text
+          end
+        end
+        path, line, match = candidates.first if candidates.length == 1
+      end
+      unless supported && node.simple? && text && !text.include?("\n") && match && match[2] == text && !text.empty?
+        @coverage << { 'context' => 'list_item', 'file' => path, 'line' => line,
+                       'reason' => 'Only unambiguously mapped, single-line outline list text with simple content is editable.' }
+        return
+      end
+      return if @only && @only != path
+      relative = Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+      return if @settings.fetch('exclude').any? { |glob| File.fnmatch?(glob, relative, File::FNM_PATHNAME | File::FNM_DOTMATCH) }
+      headings = []
+      section_index = nil
+      parent = node.parent
+      while parent
+        if parent.context == :section && parent.title
+          headings.unshift(parent.title)
+          section_index ||= @section_indexes[parent]
+        end
+        parent = parent.parent
+      end
+      @paragraphs << {
+        'id' => AsciidocPubkit.hash_text([path, line, text].join("\0"))[0, 16],
+        'file' => path, 'line' => line, 'end_line' => line, 'column' => match[1].length + 1,
+        'prefix' => match[1], 'suffix' => match[3], 'kind' => 'list-item',
+        'section_index' => section_index, 'headings' => headings, 'text' => text
+      }
     end
 
     def collect(node)
+      if scope == 'lists'
+        collect_list_item(node) if node.context == :list_item
+        return
+      end
       if %i[list_item table quote verse listing literal pass].include?(node.context)
         @coverage << { 'context' => node.context.to_s, 'reason' => 'Not reviewed as running prose.' }
       end

data/lib/asciidoc_pubkit/rules.rb

@@ -213,7 +213,7 @@ module AsciidocPubkit
         'id' => AsciidocPubkit.hash_text([paragraph['id'], rule, offset, match].join(':'))[0, 16],
         'paragraph_id' => paragraph['id'], 'rule' => rule, 'severity' => severity,
         'file' => paragraph['file'], 'line' => paragraph['line'] + prefix.count("\n"),
-        'column' => (prefix.rindex("\n") ? prefix.length - prefix.rindex("\n") : prefix.length + 1),
+        'column' => (prefix.rindex("\n") ? prefix.length - prefix.rindex("\n") : prefix.length + paragraph.fetch('column', 1)),
         'match' => match, 'question' => question
       }
     end

data/lib/asciidoc_pubkit/session.rb

@@ -4,7 +4,7 @@ require 'tmpdir'
 
 module AsciidocPubkit
   class Session
-    SCHEMA = 2
+    SCHEMA = 3
 
     def self.scan(entry, options)
       settings = Settings.new(entry, options)
@@ -12,7 +12,7 @@ module AsciidocPubkit
       unless document.diagnostics.empty?
         raise Error, "Document diagnostics must be resolved before scanning:\n" + document.diagnostics.map { |d| "#{d['severity']}: #{d['message']}" }.join("\n")
       end
-      default_output = settings.data['scope'] == 'headings' ? '.pubkit/headings' : '.pubkit/review'
+      default_output = { 'headings' => '.pubkit/headings', 'lists' => '.pubkit/lists' }.fetch(settings.data['scope'], '.pubkit/review')
       destination = File.expand_path(options.fetch(:output, default_output))
       replacing = File.exist?(destination) || File.symlink?(destination)
       if replacing
@@ -95,13 +95,18 @@ module AsciidocPubkit
       File.write(path, JSON.pretty_generate(value) + "\n")
     end
 
-    def self.protected_content(document)
+    def self.protected_content(document, allowed_anchor_lines: {})
       document.sources.to_h do |path, raw|
         paragraphs = document.paragraphs.select { |p| p['file'] == path }
         heading_scope = document.scope == 'headings'
         editable_headings = document.headings.select { |h| h['file'] == path }.to_h { |h| [h['line'], h] }
+        editable_items = document.scope == 'lists' ? paragraphs.to_h { |p| [p['line'], p] } : {}
         editable_lines = heading_scope ? [] : paragraphs.flat_map { |p| (p['line']..p['end_line']).to_a }
         outside = raw.lines.each_with_index.filter_map do |line, index|
+          next if allowed_anchor_lines.fetch(path, []).include?(index + 1)
+          if (item = editable_items[index + 1])
+            next [item['prefix'], '<editable-list-text>', item['suffix']]
+          end
           next if editable_lines.include?(index + 1)
           if heading_scope && (heading = editable_headings[index + 1])
             # Keep a positional placeholder: removing entire lines would hide reordering.
@@ -160,6 +165,7 @@ module AsciidocPubkit
       raise Error, 'Sources have changed since scanning. Create a new scan before generating a prompt.' unless stale.empty?
       language = Language.validate!(@manifest.fetch('settings').fetch('language'), operation: 'review')
       return heading_prompt(mode, language) if @manifest.fetch('settings').fetch('scope', 'prose') == 'headings'
+      list_scope = @manifest['settings']['scope'] == 'lists'
       criteria = @manifest.fetch('writing_criteria')
       instructions = <<~TEXT
         # Japanese manuscript review
@@ -184,7 +190,7 @@ module AsciidocPubkit
         After editing, reread each paragraph in context. Report unresolved issues and do not claim publication readiness.
         Mechanical verification does not establish semantic correctness.
 
-        #{review_process('paragraph', mode)}
+        #{review_process(list_scope ? 'list item' : 'paragraph', mode)}
 
         ## Shared prose criteria
 
@@ -213,6 +219,18 @@ module AsciidocPubkit
         Coverage notices: #{@document['coverage'].length}
 
       TEXT
+      if list_scope
+        instructions.sub!('running-prose paragraphs', 'single-line outline list item text')
+        instructions.sub!('proposed paragraph revisions', 'proposed list item revisions')
+        instructions.sub!('Do not change excluded content, lists, tables, quotations, or other files.',
+                          'Preserve list markers, nesting, order, continuation syntax, and inline tokens. Do not edit running prose, excluded list items, tables, quotations, or other files.')
+        instructions.sub!('running-prose edit scope', 'selected list-text edit scope')
+        instructions.sub!('Only source-mapped running-prose paragraphs are reviewed.', 'Only unambiguously source-mapped, single-line simple unordered or ordered list text is reviewed.')
+        instructions.sub!('Headings, lists, tables, quotations, code, and passthrough blocks are not prose-reviewed in this release.',
+                          'Multiline, description, checklist, compound, and reused-source list items remain protected. Running prose, headings, tables, quotations, code, and passthrough blocks are not reviewed in this session.')
+        instructions.sub!('the supplied prose/body context omits lists and other excluded blocks',
+                          'this session supplies only selected list text and heading labels; running prose and other excluded blocks are omitted')
+      end
       instructions << <<~TEXT
         ## Reading order
 
@@ -232,7 +250,7 @@ module AsciidocPubkit
           instructions << "## Context\n\n#{prompt_data(JSON.generate(context), 'json')}\n"
           previous_context = context
         end
-        instructions << "### Paragraph #{paragraph['id']} — lines #{paragraph['line']}–#{paragraph['end_line']}\n\n"
+        instructions << "### #{list_scope ? 'List item' : 'Paragraph'} #{paragraph['id']} — lines #{paragraph['line']}–#{paragraph['end_line']}\n\n"
         instructions << prompt_data(paragraph['text'], 'text') << "\n"
         related = findings_by_paragraph.fetch(paragraph['id'], [])
         if related.empty?
@@ -252,7 +270,7 @@ module AsciidocPubkit
       document.diagnostics.each { |d| issues << { 'kind' => 'parse-diagnostic', 'message' => d['message'] } }
       old_paths = @manifest['sources'].map { |source| source['path'] }.sort
       issues << { 'kind' => 'source-set-changed', 'message' => 'The included source file set changed.' } if old_paths != document.sources.keys.sort
-      current = self.class.protected_content(document)
+      current = self.class.protected_content(document, allowed_anchor_lines: permitted_anchor_lines(document))
       @manifest['protected'].each do |path, saved|
         next if current[path] == saved
         issues << { 'kind' => 'protected-content-changed', 'file' => path,
@@ -288,6 +306,21 @@ module AsciidocPubkit
 
     private
 
+    def permitted_anchor_lines(document)
+      return {} unless @manifest['settings']['scope'] == 'headings' && @manifest['settings']['preserve_heading_ids']
+      allowed = Hash.new { |hash, path| hash[path] = [] }
+      @document.fetch('headings', []).each do |saved|
+        anchor = saved['permitted_id_anchor']
+        next unless anchor
+        current = document.headings.find { |heading| heading['index'] == saved['index'] && heading['file'] == saved['file'] }
+        next unless current && current['section_id'] == saved['section_id']
+        line = current['line'] - 1
+        next unless line.positive? && document.sources.fetch(current['file']).lines[line - 1].chomp == anchor
+        allowed[current['file']] << line
+      end
+      allowed
+    end
+
     def comparison_structure(structure, headings, heading_scope)
       editable = headings.map { |h| h['index'] }
       structure.each_with_index.filter_map do |node, index|
@@ -311,7 +344,11 @@ module AsciidocPubkit
         Preserve section count, order, hierarchy, IDs, references, attributes, include directives,
         inline tokens, title markers, and all content outside the selected title spans.
         Title-derived section IDs can change after a title edit. Keep IDs unchanged;
-        otherwise report the concern and leave the title for a separate ID migration.
+        when permitted_id_anchor is present in the saved heading metadata, you may insert
+        that exact anchor on the line immediately before its heading to preserve the old ID.
+        This is the only authorized addition outside title spans. Do not edit existing anchors,
+        invent IDs, or add anchors for other headings. Without that permission, report the
+        concern and leave the title for a separately authorized ID preservation task.
         Preserve the configured fixed section names; do not rename them merely for variety.
         Automated findings are review candidates, not proven defects.
         Do not invent facts, guarantees, implementation mechanisms or benefits.
@@ -343,7 +380,8 @@ module AsciidocPubkit
 
         ## Coverage and reading order
 
-        Only selected, unambiguously source-mapped plain ATX section titles are editable.
+        Only selected, unambiguously source-mapped plain ATX section titles and explicitly
+        permitted old-ID anchor additions are editable.
         Document titles, old-style headings, converted inline titles and attribute-expanded
         titles remain protected. Body coverage excludes lists, tables, quotations and code;
         use needs-evidence when the supplied body cannot establish a title's scope.
@@ -381,11 +419,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/settings.rb

@@ -31,20 +31,24 @@ module AsciidocPubkit
       base = @path ? File.dirname(@path) : File.dirname(File.expand_path(entry))
       language = Language.validate!(options[:language] || review.fetch('language', Language::DEFAULT), operation: 'review')
       scope = options.fetch(:scope, 'prose')
-      raise Error, 'scope must be prose or headings.' unless %w[prose headings].include?(scope)
+      raise Error, 'scope must be prose, headings, or lists.' unless %w[prose headings lists].include?(scope)
       if scope == 'headings' && (options[:rules] || options[:style])
         raise Error, 'Heading scans use --heading-rules, not prose --rules or --style.'
       end
-      if scope == 'prose' && options[:heading_rules]
+      if scope != 'headings' && options[:preserve_heading_ids]
+        raise Error, '--preserve-heading-ids requires --scope headings.'
+      end
+      if scope != 'headings' && options[:heading_rules]
         raise Error, '--heading-rules requires --scope headings.'
       end
       heading_rules_path = options[:heading_rules] ? File.expand_path(options[:heading_rules]) : (review['heading_rules'] ? File.expand_path(review['heading_rules'], base) : HeadingRuleSet.default_path(language))
       rules_path = options[:replacement] ? RuleSet.default_path(language) : options[:rules] ? File.expand_path(options[:rules]) : (review['rules'] ? File.expand_path(review['rules'], base) : RuleSet.default_path(language))
       @data = {
         'scope' => scope,
+        'preserve_heading_ids' => !!options[:preserve_heading_ids],
         'heading_rules' => scope == 'headings' ? HeadingRuleSet.load(heading_rules_path) : nil,
         'heading_rules_path' => heading_rules_path,
-        'rules' => scope == 'prose' ? RuleSet.load(rules_path) : nil,
+        'rules' => scope != 'headings' ? RuleSet.load(rules_path) : nil,
         'rules_path' => rules_path,
         'language' => language,
         'style' => options[:style] || review.fetch('style', 'preserve'),

data/lib/asciidoc_pubkit.rb

@@ -9,7 +9,7 @@ require 'pathname'
 require 'optparse'
 
 module AsciidocPubkit
-  VERSION = '0.8.4'
+  VERSION = '0.8.6'
   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.6
 platform: ruby
 authors:
 - CyberGarage
@@ -37,8 +37,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Generate Japanese technical writing prompts, review AsciiDoc prose and
-  section headings separately, verify protected manuscript content, and explicitly
+description: Generate Japanese technical writing prompts, review AsciiDoc prose, section
+  headings, and list text separately, verify protected manuscript content, and explicitly
   apply prose-only mechanical replacements.
 executables:
 - asciidoc-pubkit