asciidoc-pubkit 0.6.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ce6fe84fae75593d9444c1db5d7abb1f6c96823b77376f90750d9554358af76
-  data.tar.gz: 924c12f91b714b34c1883c5a0583259d2c97989a328d412e6648d681de01984c
+  metadata.gz: 5e6439ccb97f49f7e31290cb8d60b1f361cf444889ac0631cdd1f9e28f8a0d9c
+  data.tar.gz: 484ff3e7ac4475ea693ff7d5751bc34e1537b66dda90bb7d425bb55acb467322
 SHA512:
-  metadata.gz: b194a8c6af0423b90c41275a1287bf1bdf0b6edee930a27b99bf9cddcce15d8f348e4ea58b3008e2f0f2ef533c9b4a4d43cd74262d3cd01c00b051e96aead0ba
-  data.tar.gz: ea6b5543a41d7f7d4780b3626f1e33797c55198d428f413295e9576894fc30e92b6ca890b7461382ac069612b7a48027250bcd8c6ef937bc59fd205bc5f58be6
+  metadata.gz: 9ccf0130e06770e7b12774385daab670fffde6a128e83af1d67300ada91ea6c15fc281645cfae6da6b7b009cca36d01429287ee36461c11f2d43c439d8307fe5
+  data.tar.gz: f70b717d0633729647ac733670604e3d6ace15354efc31167f8af8994b62531ddba1c74f6456c293ccf16bbee4833ddbd2efb655c520151edee6b6559d94ca0c

data/CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
-## Unreleased
+## 0.8.0 — 2026-10-01
+
+- Add explicit `replace check`, `replace diff`, and `replace apply` commands for
+  mapped running prose using a strict subset of prh-format YAML rules. Protect
+  blocks and recognized inline spans, reject overlapping edits, test rule specs,
+  and validate staged sources before applying replacements without MeCab or AI.
+
+## 0.6.3 — 2026-10-01
+
+- Summarize review and scoring features at the start of the README architecture
+  section, including AsciiDoc parsing, separate scopes, source-aligned static
+  analysis, Japanese morphology, contextual prompts and baseline verification.
+
+- Add separate `review scan --scope headings` sessions with packaged heading
+  criteria and strict custom heading rules. Keep prose as the default and
+  scoring scope; supply the full outline and read-only body evidence in one
+  prompt without invoking an AI CLI. Accept mixed heading forms and leave
+  section-role and body-agreement judgments to the reviewer.
+- Permit mapped plain ATX section title edits in heading sessions while
+  protecting body text, structure and section IDs. Report unsupported title
+  mapping, retain stale-source and artifact checks, and require fresh sessions
+  for schema 2. Generated section ID changes fail mechanical verification.
+  Use separate default output directories for prose and heading sessions and
+  protect physical titles reused by multiple includes.
+
+- Introduce the review and scoring concepts before the architecture diagrams,
+  with a table linking prose principles, implementation mechanisms, and their
+  source files. Distinguish prompt guidance from mechanical guarantees.
 
 ## 0.6.2 — 2026-10-01
 
@@ -40,6 +67,8 @@
 
 ## 0.6.0 — 2026-09-30
 
+Initial public release, including the earlier development work.
+
 - Add `writing criteria` and `writing prompt` commands backed by one packaged
   Japanese technical prose guide. Include that guide in saved review prompts.
 - Organize the CLI into `writing` and `review` groups and accept `--lang ja` on
@@ -49,8 +78,6 @@
 - Refine Japanese review questions for redundant qualifications and generic
   recaps, and document the editorial sources and contextual limits.
 
-## 0.1.3 — 2026-09-29
-
 - Consolidate Japanese review candidates for terminology, compressed noun
   relationships, operations, and negative qualifications in the packaged rules.
 - Suppress literal candidates contained in longer matched terms, preserving
@@ -61,16 +88,11 @@
 - Add `review scan --yes` (`-y`) and `--no-input` for batch execution.
 - Preserve previous sessions until replacement scan artifacts are ready.
 
-## 0.1.2 — Released
-
 - Package default Japanese review rules as a validated UTF-8 YAML file.
 - Support custom rule files through `review scan --rules` and `review.rules`.
 - Save resolved rules in sessions for reproducible prompts and verification.
 - Add concept, distinction, and negative meaning review candidates.
 - Add a Make target for running a local checkout with arbitrary CLI arguments.
-- Require a new review session when upgrading from earlier tool versions.
-
-## 0.1.1 — Released
 
 - Add contextual phrases, compound nouns, and potential and causative verb forms.
 - Add requested abstract nouns, degree adjectives, and vague predicates.
@@ -79,9 +101,6 @@
 - Record analyzer and dictionary fingerprints in review sessions.
 - Add an explicit literal mode for environments without MeCab.
 - Reject incompatible dictionaries and unavailable analyzers with setup guidance.
-- Require a new review session when upgrading from 0.1.0.
-
-## 0.1.0 — Released
 
 - Add AsciiDoc running-prose extraction with checked source locations.
 - Add Japanese review candidates and configurable terminology checks.

data/README.md

@@ -7,15 +7,21 @@
 
 A toolkit for authoring and reviewing AsciiDoc books.
 
-Version 0.6.2 provides shared Japanese technical writing criteria, an authoring
-prompt, contextual review prompts, manuscript scoring, and baseline verification
-for edited manuscripts.
+Version 0.8.0 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.
 The CLI, diagnostics, documentation, and generated instructions are in English.
 Japanese text is retained in manuscript excerpts, rule dictionaries, and fixtures.
 
 ## Status
 
-The CLI does not automatically rewrite manuscripts or publish books. EPUB, image,
+Version 0.6.3 adds separate heading review with `review scan --scope headings`.
+See [Heading review](#heading-review).
+
+Version 0.8.0 adds explicit prose replacements with `replace apply`;
+see [Prose replacements](#prose-replacements). Review and scoring do not edit
+manuscripts. The CLI does not publish books. EPUB, image,
 and book scaffolding commands are planned extensions, not available features.
 
 Ruby 3.2 or later is required. Asciidoctor is installed as a gem dependency.
@@ -30,7 +36,7 @@ configured model provider. No scoring mode edits manuscripts.
 
 Version 0.1.1 added morphological analysis. Version 0.1.0 used literal matching.
 
-The CLI has `writing` and `review` command groups. Both default to `--lang ja`.
+The CLI has `writing`, `review`, and `replace` command groups. All default to `--lang ja`.
 Language-specific criteria live under `data/writing/<language>/`; review rules
 use `data/review-rules.<language>.yml`. Writing and review have separate lists
 of supported languages, so a future writing language need not imply review
@@ -80,7 +86,7 @@ Add the gem to your project's `Gemfile` to manage its version with Bundler:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'asciidoc-pubkit', '~> 0.6.2'
+gem 'asciidoc-pubkit', '~> 0.8.0'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -102,7 +108,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.6.2.gem
+gem install ./asciidoc-pubkit-0.8.0.gem
 asciidoc-pubkit --version
 ```
 
@@ -126,7 +132,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.6.2.
+review or writing criteria are shipped in 0.8.0.
 
 For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
 paragraphs deliberately contain review candidates; its code block must remain
@@ -196,7 +202,7 @@ Use `ARGS` instead of `make review scan book.adoc`: Make interprets positional
 words as build targets, not CLI arguments. Avoid `make -C` when manuscript paths
 should remain relative to the current directory, because it changes directories.
 
-## Install the morphological analyzer (0.1.1 and later)
+## Install the morphological analyzer
 
 On macOS with Homebrew:
 
@@ -298,6 +304,91 @@ session after moving a project. Keep `.pubkit/` and generated prompts out of Git
 when they contain private manuscript material. Rule settings and glossary contents
 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.
+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.
+Neither scan nor prompt invokes an AI CLI or edits a manuscript. Give the generated
+prompt to your reviewer separately.
+
+```sh
+asciidoc-pubkit review scan book.adoc --scope headings --output .pubkit/headings
+asciidoc-pubkit review prompt .pubkit/headings --mode diagnose --output headings-diagnosis.md
+# Generate a revision prompt when ready to edit:
+asciidoc-pubkit review prompt .pubkit/headings --mode revise --output headings-review.md
+# After the external review and edits:
+asciidoc-pubkit review verify .pubkit/headings
+
+# Establish a fresh prose baseline after finishing heading edits:
+asciidoc-pubkit review scan book.adoc --scope prose --output .pubkit/prose
+asciidoc-pubkit review prompt .pubkit/prose --output prose-review.md
+asciidoc-pubkit review verify .pubkit/prose
+```
+
+Heading prompts contain the full parsed section outline, selected headings and
+all selected source-mapped prose paragraphs once as read-only evidence. They
+compare parents, siblings, descendants and the corresponding body. Body content
+outside prose coverage is not supplied; insufficient evidence must be recorded
+as `needs-evidence`. `--only` and `review.exclude` select editable headings and
+body evidence while retaining the full outline as context. All excerpts are data,
+never executable reviewer instructions. Both criteria files and resolved rules
+are frozen in the session.
+
+Default heading rules accept term labels, noun phrases, questions, action
+phrases, principles, conclusions and learning directions. They flag limited
+promotional/vague phrases, glossary variants and identical sibling titles as
+review candidates. They do not apply prose weak-predicate or sentence-ending
+rules, require nominalization, or impose a character limit. Role and body
+agreement are contextual reviewer judgments, not mechanically proven findings.
+
+Only plain ATX section titles whose source cursor and original title match are
+editable. Document titles, old-style underlined headings, attribute-expanded
+and converted inline titles and physical title lines reused by multiple includes remain protected.
+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
+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
+finish an ongoing review with its original tool before establishing a new baseline.
+`review score` continues to support prose only and rejects `--scope`.
+
+Heading rules use `--heading-rules FILE`, then configuration
+`review.heading_rules`, then `data/heading-rules.ja.yml`. A custom file replaces
+the entire heading rule set. Each scan loads only the rules for its selected
+scope; an unavailable rule file for the other scope does not prevent it.
+`--heading-rules` requires `--scope headings`;
+prose `--rules` and `--style` cannot be passed to a heading scan.
+
+```yaml
+schema_version: 1
+terms:
+  book-heading-cue:
+    terms: [シームレス]
+    question: 'Check the claimed behavior against the section evidence.'
+fixed_titles: [はじめに, 参考文献, まとめ]
+duplicate_siblings: true
+style: mixed
+```
+
+All five keys are required; unknown keys, invalid types and YAML aliases are
+rejected. `terms` maps nonempty rule names to exactly `terms` (unique nonempty
+strings) and `question` (nonempty English guidance). `fixed_titles` contains
+unique nonempty titles exempt from mechanical candidates; it does not expand
+the edit scope or prove correctness. `duplicate_siblings` is boolean. `style`
+is `mixed` (default), `nominal`, or `action`; explicit preferences generate
+advisory ending cues rather than a complete grammatical classification. Keep
+questions, principles and justified exceptions. Heading phrase and glossary
+matches respect exact `review.allows` entries, protected inline masking and
+one-based Unicode source columns. MeCab remains the default; only explicit
+`--tokenizer literal` disables it.
+
 ### Prompt
 
 ```sh
@@ -334,7 +425,7 @@ An omitted `:lang:` attribute uses the selected review language.
 asciidoc-pubkit review verify .pubkit/review
 ```
 
-Verification compares the current source set, document structure, content outside
+For prose sessions, verification compares the current source set, document structure, content outside
 reviewed paragraphs, and recognized protected inline tokens with the baseline.
 It reports remaining candidates and numeric changes separately. Existing candidates
 do not make verification fail. Numeric changes require manual review but do not
@@ -354,6 +445,86 @@ or release readiness: `meaning_verified` is always `false`.
 
 ## How review and scoring work
 
+### Features
+
+- **Structure-aware AsciiDoc parsing.** Asciidoctor parses local includes,
+  conditionals, attributes and section hierarchy before review targets are
+  selected. Prose selection distinguishes paragraphs from lists, tables,
+  quotations and code blocks; supported inline constructs are masked rather
+  than treated as ordinary prose.
+- **Separate heading and prose review.** Each scan selects one
+  scope with its own rules, prompt and edit permissions. Heading review uses
+  the outline and body as context while protecting body text; prose review
+  protects headings. Mixed heading forms are accepted by default. See
+  [Heading review](#heading-review).
+- **Source-aligned static analysis.** Candidates identify the original source
+  file, line and one-based Unicode column, with a rule ID and review question.
+  Source text is checked against parser locations; unresolved mappings produce
+  coverage notices instead of guessed edit targets. Matches locate passages
+  for review, not proven defects.
+- **Japanese morphological analysis.** MeCab with UTF-8 IPADIC recognizes
+  configured inflected predicates and adjectives, retaining original surfaces,
+  dictionary forms and negative-form information in morphological prose
+  findings. Literal matching is available only through explicit selection.
+- **Contextual review in one prompt.** A single Markdown file carries saved
+  criteria, settings, candidates and manuscript evidence. All selected prose
+  paragraphs appear once, including those without candidates, with heading and
+  neighboring context. The reviewer records decisions and checks meaning;
+  generating the prompt does not edit the manuscript or invoke a model.
+- **Book-specific rules and terminology.** Strict YAML rule sets, a glossary,
+  allow lists and exclusions adapt candidate detection to the manuscript.
+  Heading rules can express a book's preferred form while allowing justified
+  exceptions. Resolved rules and criteria are saved with each session.
+- **Baseline-based preservation checks.** Source snapshots and artifact hashes
+  make the review baseline reproducible and detect stale or altered evidence.
+  Verification checks protected content, source membership, structure and
+  analyzer identity after external edits. It keeps `meaning_verified: false`;
+  semantic correctness remains a review judgment.
+- **Local analysis and distinct scoring paths.** Default analysis runs locally
+  without a model call. Prose scoring reports candidate density; explicit
+  `review score --agent` optionally invokes an installed Codex or Claude CLI
+  for readability ratings. Candidate density, model judgments and development
+  benchmark accuracy remain separate measures.
+
+### Concept
+
+The goal is Japanese technical prose that readers can understand, use, and
+verify, with claims bounded by evidence and technical meaning preserved.
+Clarity includes a paragraph's purpose, concrete operations and referents,
+actors and objects, conditions and consequences, logical connections, and its
+relationship to headings, figures, tables, and code. "Who does what" is one
+part of that goal. Clear prose also retains precise terminology, necessary
+negation, uncertainty, and implementation constraints.
+
+The toolkit supports that goal through shared writing criteria, contextual
+review prompts, source-aligned candidate detection, baseline verification,
+and distinct scoring and development evaluation paths. Mechanical rules locate
+passages to inspect; the reviewer judges their meaning from context and source
+evidence. The writing and review prompts guide a human or external agent in
+planning and revising complete paragraphs. They do not automatically reconstruct
+subjects and objects or rewrite manuscripts. Model-based readability evaluation
+is available only through explicit `review score --agent`.
+
+The table identifies both implemented mechanisms and guidance carried by the
+prompts. A criterion in a prompt is a review instruction, not a guarantee that
+the code can detect or verify it.
+
+| Supported principle or behavior | How it is realized | Implementation or criteria |
+| --- | --- | --- |
+| Write for a technical purpose and the reader's decisions | Shared criteria ask what a paragraph explains and what an engineer can decide or verify; writing prompts include those criteria | [Paragraph purpose](data/writing/ja/criteria.md#start-with-the-paragraphs-technical-purpose), [Writing](lib/asciidoc_pubkit/writing.rb) |
+| Make actors, objects, actions, conditions, and results recoverable | Review instructions ask the reviewer to resolve omitted elements from context, while allowing unambiguous omission | [Paragraph revision](data/writing/ja/criteria.md#revise-the-complete-paragraph), [Review prompt](lib/asciidoc_pubkit/session.rb) |
+| Replace vague abstraction, weak predicates, and metaphors with concrete explanations | Rules locate limited terms and inflected predicates; the criteria require identifying the actual referent, operation, policy, or effect before revising | [Concrete referents](data/writing/ja/criteria.md#replace-abstraction-with-the-thing-being-discussed), [Metaphor criteria](data/writing/ja/criteria.md#explain-metaphorical-operations-from-evidence), [Rules](lib/asciidoc_pubkit/rules.rb) |
+| Distinguish reader instructions, actual behavior, and available capabilities | The shared criteria preserve the difference between requests, automatic execution, and optional operations | [Instructions, behavior, and capabilities](data/writing/ja/criteria.md#distinguish-instructions-behavior-and-capabilities) |
+| Connect claims into coherent paragraphs | Prompts include all selected paragraphs and neighboring context; criteria require explicit referents, comparisons, causal relationships, and complete paragraph revision | [Relationships](data/writing/ja/criteria.md#make-relationships-explicit), [Review prompt](lib/asciidoc_pubkit/session.rb) |
+| Keep claims within their evidence and preserve meaning | Review guidance asks for implementation, test, or primary-source evidence and checks omissions and unsupported additions; unresolved facts remain unresolved | [Evidence and scope](data/writing/ja/criteria.md#keep-claims-within-their-evidence-and-purpose), [Paragraph revision](data/writing/ja/criteria.md#revise-the-complete-paragraph) |
+| Preserve technical distinctions, terminology, and justified prose choices | Criteria protect identifiers, values, conditions, negation, and necessary repetition; glossary rules, allow lists, and contextual questions support project terminology | [Terminology](data/writing/ja/criteria.md#preserve-exact-technical-terminology), [Packaged rules](data/review-rules.ja.yml), [Settings](lib/asciidoc_pubkit/settings.rb) |
+| Review generated-prose patterns without mechanical deletion | Framing, contextual phrases, style, and repeated-ending checks produce candidates; shared criteria reject fixed sentence-length targets and needless synonym changes | [Generated-prose patterns](data/writing/ja/criteria.md#remove-generated-prose-patterns-without-flattening-the-meaning), [Rules](lib/asciidoc_pubkit/rules.rb) |
+| Keep headings, illustrations, tables, and code consistent with the explanation | Writing criteria address scope, comparisons, identifiers, and conceptual simplifications; review prompts constrain edits to the selected scope and protect other elements | [Headings, figures, and code](data/writing/ja/criteria.md#headings-and-the-relation-to-figures-and-code), [Review scope](lib/asciidoc_pubkit/session.rb) |
+| Make detection traceable and coverage explicit | Asciidoctor source mapping, offset-preserving inline masking, and MeCab/IPADIC produce source-aligned evidence; ambiguous or excluded passages have coverage notices | [Document](lib/asciidoc_pubkit/document.rb), [Morphology](lib/asciidoc_pubkit/morphology.rb), [Rules](lib/asciidoc_pubkit/rules.rb) |
+| Preserve a reproducible and safe review baseline | Sessions save source snapshots, resolved rules, criteria, and analyzer identity; integrity checks and verification protect content outside editable prose | [Session](lib/asciidoc_pubkit/session.rb), [Rule validation](lib/asciidoc_pubkit/rule_set.rb) |
+| Keep manuscript indicators, readability judgments, and detector accuracy distinct | Default scoring measures candidate density; optional local CLI evaluation judges readability; annotated development benchmarks measure detection and evaluate preservation separately | [Score](lib/asciidoc_pubkit/score.rb), [Local evaluator](lib/asciidoc_pubkit/local_evaluator.rb), [Development benchmark](benchmark/prose.rb) |
+| Make automation explicit and its limits visible | Default analysis runs locally with no model call; only explicit scoring requests invoke an external CLI. Manuscripts are not edited, and verification retains `meaning_verified: false` | [CLI](lib/asciidoc_pubkit/cli.rb), [Local evaluator](lib/asciidoc_pubkit/local_evaluator.rb), [Session](lib/asciidoc_pubkit/session.rb) |
+
 This section explains the implementation independently of command syntax.
 [Review workflow](#review-workflow) covers commands and session handling;
 [Score an AsciiDoc manuscript](#score-an-asciidoc-manuscript) covers scoring options.
@@ -547,6 +718,7 @@ review:
   language: ja
   style: desu-masu
   tokenizer: mecab
+  # heading_rules: heading-rules.yml  # Separate heading rule set
   # Optional overrides (dictionary paths are relative to this file):
   # mecab_command: /opt/homebrew/bin/mecab
   # mecab_dictionary: /opt/homebrew/lib/mecab/dic/ipadic
@@ -581,6 +753,107 @@ Regex patterns are not interpreted in glossary or allow-list entries. Unknown
 configuration keys are rejected. A bare `mecab_command` is resolved through PATH;
 use an absolute path for an explicit executable override.
 
+## Prose replacements
+
+Available starting with version 0.8.0.
+It applies author-supplied mechanical replacement rules without MeCab or an AI
+CLI. Review candidates and glossary variants remain advisory and are never
+implicitly applied. Replacement rules are separate from review rules.
+
+```sh
+asciidoc-pubkit replace check book.adoc --rules replacements.yml
+asciidoc-pubkit replace diff book.adoc --rules replacements.yml
+asciidoc-pubkit replace apply book.adoc --rules replacements.yml
+```
+
+`check` reports original text, proposed text, rule IDs (`rule-1`, etc.), source
+paths, one-based Unicode lines/columns, and a coverage-notice count. Its exit code
+is 1 when replacements are available, 0 otherwise. `diff` previews unified diffs
+without editing; it requires the external `diff` command. `apply` explicitly
+authorizes source replacement without prompting. Successful diff/apply commands
+return 0; invalid rules, conflicts, unsafe edits, and input/output failures return
+2. Check/diff accept `--output` for a new file only; apply rejects `--output`.
+
+All three accept `--lang ja`, `--base-dir`, `--config`, and `--only` (an included
+source file). Normal configuration discovery and `review.base_dir`, `language`,
+`attributes`, and `exclude` control parsing and selection. `--rules` is required;
+`review.rules` and glossary entries do not supply replacement rules. There are
+no built-in replacement rules and no automatic search for `prh.yml`.
+
+### Limited prh-format rules
+
+The supported format is a strict subset of [prh](https://github.com/prh/prh):
+
+```yaml
+version: 1
+rules:
+  - expected: '®'
+    pattern: '&reg;'
+  - expected: '($1)'
+    pattern: '/（([^（）\r\n]+)）/'
+    specs:
+      - from: '設定（任意）'
+        to: '設定(任意)'
+  - expected: '/'
+    patterns:
+      - '／'
+```
+
+The root contains exactly `version: 1` and `rules`. Each rule requires a string
+`expected` (empty strings permit deletion) and exactly one of `pattern` (a
+nonempty string) or `patterns` (a nonempty array of nonempty strings). Optional
+`specs` is an array of exact `from`/`to` string pairs, validated on load. Specs
+exercise the rule on plain text, not AsciiDoc selection or inline protection.
+
+Strings not beginning with `/` match literally. `/.../` denotes a regex with no
+flags; all occurrences are collected. The implementation uses Ruby regexes with
+a timeout and accepts a limited common syntax: character classes, ordinary
+captures, noncapturing groups, lookarounds, alternatives, anchors, quantifiers,
+and the escapes `\n`, `\r`, `\t`, `\d`, `\D`, `\s`, `\S`, `\w`, `\W`
+and escaped punctuation. Ruby regex character-class behavior applies; this is
+not a JavaScript regex engine or a promise of full prh equivalence. Engine-specific
+groups/escapes and flags are rejected. A leading literal slash must be expressed
+as an escaped regex, for example `/\//`. Zero-length matches are rejected.
+
+Replacement strings support `$1` through `$99` for existing capture groups and
+`$$` for a literal dollar sign. Unsupported dollar references are rejected when
+matched. Missing optional captures expand to empty strings. YAML single quotes
+are recommended to keep backslashes literal. Unknown fields, including `imports`,
+`options`, and `regexpMustEmpty`, and omitted patterns are rejected rather than
+ignored. Regex flags and prh's automatic pattern generation are not supported.
+
+### Selection and preservation
+
+Only unambiguously source-mapped running prose in the existing default review
+scope is eligible. Headings, lists, tables, quotations, listing/source, literal,
+and passthrough blocks are excluded. Recognized inline code, quotations, URLs,
+macros, and attribute references are protected by the existing conservative
+inline heuristic, not a complete inline parser. A match overlapping any protected
+span is skipped; matching is performed on the original text, never on blanked
+placeholders. Backtick-to-bold and list-marker conversions are outside this scope.
+
+Candidates are calculated once against the original sources; replacement results
+are not searched again. Overlapping edits are conflicts, not resolved by rule
+order. Matches/results containing line breaks are rejected. Source files retain
+UTF-8 bytes, original line endings, and unrelated content; repeated include
+occurrences must not create overlapping edits.
+
+Before presenting a plan, the complete captured source set is copied to temporary
+staging and reparsed. Parsing diagnostics, structural changes, new/deleted protected
+inline tokens, and protected-content/source-membership changes reject the plan.
+Relative includes within the base directory are supported. Absolute includes and
+includes whose paths depend on the original filesystem may fail staged validation;
+they are not rewritten or silently accepted. Symlink entrypoints are rejected.
+
+Apply stages all changed files beside their destinations, checks all captured
+source bytes against the plan, and renames the prepared files into place while
+preserving permission bits. An ordinary installation error restores sources
+already installed. This is not a crash-atomic transaction across multiple files;
+keep manuscripts under version control and avoid concurrent edits during apply.
+No review session is created or replaced. Existing sessions retain their original
+baselines; applying replacements can make a session stale for prompt generation.
+Mechanical validation does not establish semantic correctness.
+
 ## Rules and coverage
 
 | Rule | Severity | Purpose |
@@ -671,18 +944,18 @@ 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.6.2. Keep the original baseline for
+Sessions from earlier tool versions are not compatible with 0.8.0 (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.6.2
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.8.0
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship
 score and no requirement to eliminate every match.
 
-Only source-mapped running-prose paragraphs are reviewed. Headings, list items and
+In the default prose scope, only source-mapped running-prose paragraphs are reviewed. Headings, list items and
 their continuations, tables, quotations, code, and passthrough blocks are excluded
 from prose review. Common inline literals, macros, attribute references, URLs, and
 Japanese quotation spans are masked. Complex inline syntax can exceed the masking

data/data/heading-rules.ja.yml

@@ -0,0 +1,23 @@
+---
+schema_version: 1
+terms:
+  heading-promotion:
+    terms:
+    - シームレス
+    - 最適
+    - 完全
+    - 究極
+    question: 'Check whether this evaluation or guarantee is supported by the section. Do not add stronger claims merely to polish a title; valid technical terms may be kept.'
+  heading-vague-topic:
+    terms:
+    - いろいろ
+    - さまざまなこと
+    question: 'Check whether the heading identifies the actual subject, operation or comparison. Use the section as evidence; do not invent missing specificity.'
+fixed_titles:
+- はじめに
+- 本書の構成
+- 参考文献
+- 参照した実装ファイル
+- まとめ
+duplicate_siblings: true
+style: mixed

data/data/writing/ja/headings.md

@@ -0,0 +1,45 @@
+# Japanese technical heading criteria
+
+## Identify the section's role
+
+Determine whether the section explains a concept, structure, operation,
+comparison, principle, problem, or learning direction before suggesting a title.
+Term labels, noun phrases, definition questions, action phrases, principles,
+conclusion statements, and reader questions are all valid heading forms.
+The form alone is not a defect. A nominal action label can also describe a procedure.
+
+## Match the title to the evidence
+
+Use the corresponding section body, descendants and neighboring context to
+check the promised subject and scope. Do not add guarantees, implementation
+mechanisms, actors, causes, superlatives, or benefits absent from the source.
+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.
+
+## Compare headings with the same role
+
+Read the complete outline and compare parent, sibling and child headings.
+Align granularity and naming for sections with the same role; do not impose one
+form on every heading at the same level or throughout the book. Conceptual
+sections and procedures can intentionally use different forms.
+Repeated official terms and fixed section names are valid. Check duplicate
+siblings for ambiguity, without treating all repetition as a defect.
+
+## Respect the book's format
+
+The book owns preferred nominal or action forms, questions, fixed titles,
+length expectations and numbering. The default accepts mixed forms, without a
+universal character limit. Style candidates are advisory and admit exceptions.
+Do not mechanically nominalize action headings or replace plain language with
+abstract technical-sounding nouns. Do not reorganize, merge, split or reorder
+sections during title correction.
+
+## Record decisions and preservation concerns
+
+Review every selected heading, including headings without machine candidates.
+Record revise, keep or needs-evidence with a reason for each heading. Compare
+original and proposed titles separately for information loss and unsupported
+additions. Keep source identifiers, references and protected inline syntax.
+Mechanical verification does not establish agreement with the body or semantic
+correctness; meaning_verified remains false.

data/examples/replacements.yml

@@ -0,0 +1,17 @@
+version: 1
+
+rules:
+  - expected: '®'
+    pattern: '®'
+    specs:
+      - from: '製品®'
+        to: '製品®'
+  - expected: '($1)'
+    pattern: '/（([^（）\r\n]+)）/'
+    specs:
+      - from: '設定（任意）'
+        to: '設定(任意)'
+  - expected: ' '
+    pattern: '　'
+  - expected: '/'
+    pattern: '／'