asciidoc-pubkit 0.8.7 → 1.0.0

data/docs/replacements.md

@@ -0,0 +1,193 @@
+# Prose replacements
+
+The replacement commands apply 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`.
+
+Starting with version 0.8.2, invalid rule files report their original YAML file
+and one-based line number on the first error line, followed by the existing
+reason on the next line. Imported files and entries in pattern arrays retain
+their own source locations. For example:
+
+```text
+Error: /path/to/prh.yml:162
+Unsupported regex flags; only optional i is supported (all matches are collected).
+```
+
+Rules are validated before any manuscript is replaced. All replacement commands
+stop with exit code 2 on invalid rules, including errors found in imported files.
+
+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: '®'
+  - expected: '($1)'
+    pattern: '/（([^（）\r\n]+)）/'
+    specs:
+      - from: '設定（任意）'
+        to: '設定(任意)'
+  - expected: '/'
+    patterns:
+      - '／'
+```
+
+The root requires `version: 1` and accepts optional `rules` and `imports` arrays.
+Starting with version 0.8.1, omitted arrays default to empty. Version 0.8.0
+requires `rules` and rejects `imports`. Each rule requires a string
+`expected` (empty strings permit deletion) and exactly one of `pattern` (a
+nonempty string or, starting with version 0.8.1, a nonempty array of nonempty
+strings) or `patterns` (a nonempty array of nonempty strings). Array-valued
+`pattern` is equivalent to `patterns`; specifying both keys is rejected. 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; the
+version 0.8.1 also accepts `/.../i` for Ruby case-insensitive matching.
+Version 0.8.0 rejects all 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 other than a single `i` 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
+`options` and `regexpMustEmpty`, and omitted patterns are rejected rather than
+ignored. prh's automatic pattern generation is not supported.
+
+For example, version 0.8.1 also accepts:
+
+```yaml
+version: 1
+rules:
+  - expected: 'ハードウェア'
+    pattern:
+      - 'ハードウエア'
+      - 'ハードウェアー'
+```
+
+Each array entry uses the same literal/regex syntax and validation as a single
+pattern. Arrays do not change supported flags or overlap handling.
+
+### Limited ECMAScript boundary compatibility
+
+Version 0.8.1 translates `\b` and `\B` outside character classes into Ruby
+lookarounds with ECMAScript word-character semantics, following prh's default
+Unicode mode. Word characters are ASCII letters, digits, and underscore; Japanese
+characters are non-word characters. Thus `/\bTips\b/` matches `Tips` in
+`前Tips後`, but not in `Tips2`, `_Tips`, or `ATips`.
+With `/i`, long s (`ſ`) and Kelvin sign (`K`) also count as word characters under
+ECMAScript Unicode case folding. The generated assertions add no capture groups
+and preserve original match offsets. Inside a character class, `\b` means a
+backspace character; `\B` there is rejected. Escaped literal backslashes are
+preserved.
+
+Only the boundary assertions emulate ECMAScript. `/i` uses Ruby's
+`Regexp::IGNORECASE`; Unicode case folding can differ from JavaScript (for
+example multi-character folds). Other constructs, including whitespace classes,
+retain Ruby semantics. This is limited prh compatibility, not full ECMAScript
+conformance. Flags `g`, `m`, `s`, `u`, `y`, `d`, and `v` and duplicate `i` are
+rejected; all occurrences are already collected independently of `g`.
+
+### Importing replacement rules
+
+Version 0.8.1 supports nested `imports`; version 0.8.0 does not. For example:
+
+```yaml
+version: 1
+imports:
+  - ../../rules/prh.yml
+  - path: ./terminology.yml
+rules:
+  - expected: '®'
+    pattern: '®'
+```
+
+Each entry is a nonempty local file path string or a mapping containing exactly
+`path`. Relative paths resolve from the importing YAML file, including nested
+imports, independently of the working directory and manuscript base directory.
+Absolute local paths are also accepted; URL imports are rejected. An import-only
+file may omit `rules`. A file containing only `version: 1` is also valid and
+contributes no rules. With no imported or local rules, `check`, `diff`, and
+`apply` succeed without changing manuscript sources, and `diff` emits no patch.
+Starting with version 0.8.1, a bare `rules:`, `rules: null`, and `rules: ~`
+also contribute no local rules, just like omission or `rules: []`; imported rules
+are still loaded. Other non-array values remain invalid. This normalization
+applies only to `rules`, not to `imports` or individual rule fields.
+Every imported file must use version 1 and pass the same
+strict rule validation and specs as the entry file.
+
+Imports are loaded in listed order, recursively before each file's own rules.
+Each physical file is loaded once per plan, including repeated paths, symlink
+aliases, and shared dependencies. Rule IDs are assigned across the flattened
+set. Cycles (including symlink aliases), missing files, and import chains deeper
+than 100 files fail rather than silently omitting rules. Imported and local rules
+are combined, not overridden: overlapping replacement candidates remain errors
+and replacements are still calculated only against the original text.
+
+Import options such as `ignoreRules` and `disableImports` remain unsupported and
+are rejected. Source selection and protection are unchanged by imports.
+
+### 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.
+
+[Back to README](../README.md)

data/docs/review-workflow.md

@@ -0,0 +1,267 @@
+# Review workflow
+
+Run the following commands from the manuscript project directory:
+
+```sh
+asciidoc-pubkit review scan book.adoc --output .pubkit/review
+asciidoc-pubkit review prompt .pubkit/review --output review-prompt.md
+# Ask your agent to read review-prompt.md and revise the referenced manuscript.
+asciidoc-pubkit review verify .pubkit/review --output verification.json
+```
+
+All three commands leave manuscript files unchanged. Only the agent edits them.
+`prompt` and `verify` output files must not already exist.
+Without `--output`, `prompt` writes Markdown and `verify` writes JSON to stdout.
+`scan` defaults to `.pubkit/review` and prints a short summary. Prose scan output
+and prompts explicitly direct reviewers to a separate `--scope lists` session
+for list text; the prose baseline must remain intact.
+
+List review is optional when the assignment covers running prose only or there
+are no list descriptions to review. It is needed when the assignment includes
+list wording: the default prose scan does not review it. See [List review](list-review.md#list-review)
+for examples, supported items, and coverage limits.
+
+For a review covering all three scopes, finish and verify headings first, then
+scan and review the current prose, then scan and review the current list text.
+Create each session after the preceding phase's edits and verification. Preserve
+all earlier baselines and phase-end results; later edits in another scope may
+legitimately make an earlier session's verification fail. On re-review, choose
+unused session paths rather than replacing the previous evidence.
+
+### Scan
+
+```sh
+asciidoc-pubkit review scan book.adoc --only chapters/introduction.adoc
+asciidoc-pubkit review scan chapter.adoc --style desu-masu
+asciidoc-pubkit review scan book.adoc --attribute edition=print --base-dir .
+```
+
+If the session directory already exists, an interactive terminal asks
+`Replace it? [y/N]`. Only `y` or `yes` (case-insensitive) replaces it; any other
+answer or end of input cancels with exit status 2. Replacement resets the review
+baseline and removes old session contents. Use a different `--output` path to
+keep the previous review pass. The old session remains intact if scanning fails
+before the replacement is installed.
+
+For batch execution:
+
+```sh
+# Answer yes automatically and replace an existing review session.
+asciidoc-pubkit review scan book.adoc --yes  # short form: -y
+# Never ask; exit with status 2 if the output already exists.
+asciidoc-pubkit review scan book.adoc --no-input
+```
+
+Non-terminal stdin also disables prompting. `--yes --no-input` permits
+replacement without reading stdin. These options apply to `scan` only;
+regular files, symlinks, directories without a review session layout, and
+sessions containing the current manuscript sources cannot be replaced.
+
+An entrypoint or a standalone chapter can be scanned. Includes and conditionals
+are processed by Asciidoctor. Match the publishing build's attributes and base
+ directory to review the intended edition. `--only` selects one included source
+file while retaining the book's attributes and heading hierarchy. Its path is
+relative to the current working directory, as are other CLI path arguments.
+
+Asciidoctor runs in safe mode. Local includes must resolve inside the base
+directory. Remote includes and project-specific Asciidoctor extensions are not
+supported. In particular, custom `/shared/` include conventions must be converted
+to ordinary local paths before using this release. Parser diagnostics cause the
+scan to fail rather than silently accepting incomplete input.
+
+The session contains:
+
+```text
+.pubkit/review/
+  manifest.json    # Schema, tool version, inputs, settings, hashes, protection data
+  findings.json    # Candidate locations, rule IDs, severity, and review questions
+  document.json    # Paragraphs, heading hierarchy, structure, and coverage notices
+  baseline/       # Exact copies of the participating source files
+```
+
+Sessions use absolute source paths and are local working artifacts. Regenerate a
+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, 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.
+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. Starting with version 0.8.7, heading scans preserve
+generated IDs by default. Eligible generated headings 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. No additional
+ID-preservation option is required. Previously saved permissions remain unchanged;
+start a separate new session to obtain the default permissions, keeping the old
+baseline intact. 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`.
+
+Version 1.0.0 uses session schema 3 and requires the exact tool version saved in
+the session. Preserve or finish an ongoing review with its original tool before
+establishing a new baseline in a separate directory.
+`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
+asciidoc-pubkit review prompt .pubkit/review --mode revise --output review-prompt.md
+asciidoc-pubkit review prompt .pubkit/review --mode diagnose
+```
+
+`revise` is the default and asks the agent to edit relevant prose. `diagnose` asks
+for findings and proposed revisions without editing. Both modes require the agent
+to distinguish **revise**, **keep**, and **needs-evidence** decisions. Each decision
+needs a passage-specific reason. Whether a matched string remains or disappears
+cannot determine that decision; unchanged paragraphs and remaining candidates
+must not receive automatic `keep` records. Unreviewed items remain pending.
+
+Version 0.8.4 prompts require the reviewer to reconcile decisions with actual
+edits (or proposed revisions in diagnose mode), review paragraphs or headings
+without candidates, and inspect newly detected or remaining candidates after
+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.
+
+The single Markdown output includes every selected paragraph once, in document
+order, with the shared criteria saved at scan time, candidates, saved settings,
+and preservation instructions. Paragraph
+text uses fenced text blocks; metadata uses compact JSON. File and heading context
+is shared by consecutive paragraphs, and candidates inherit their file and
+paragraph ID. Adjacent entries provide neighboring context without repeating text.
+The prompt asks the agent to read manageable ranges with neighboring paragraphs
+at boundaries and track completed paragraph IDs and candidate decisions. It also
+requires review of paragraphs with no machine matches. Large manuscripts can
+still exceed a context window if the entire prompt is loaded at once. Initial
+support is for local prose correction, not chapter reorganization.
+
+Source hashes are checked before generating a prompt. Modified sources, modified
+session artifacts, and incompatible session versions require a fresh scan.
+`review scan`, `review prompt`, and `review verify` accept `--lang ja`; prompt and
+verify check the value against the session language. A non-Japanese language in
+`--lang`, `review.language`, or an explicit AsciiDoc `:lang:` attribute is rejected.
+An omitted `:lang:` attribute uses the selected review language.
+
+### Verify
+
+```sh
+asciidoc-pubkit review verify .pubkit/review
+```
+
+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
+by themselves fail mechanical verification.
+
+Non-prose comparison ignores empty separator lines and trailing whitespace;
+listing, literal, and passthrough block content is additionally compared as parsed
+lines. Inline protection is heuristic, not a complete AsciiDoc inline parser.
+Successful verification does not prove meaning preservation, technical accuracy,
+or release readiness: `meaning_verified` is always `false`. Verification does
+not read candidate decision records or certify editorial completion. A passing
+mechanical result must be reported separately from the reviewer's quality and
+completion assessment.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Command completed; verification found no mechanical violations |
+| `1` | Verification found protected-content, structure, source, or parsing issues |
+| `2` | Invalid arguments, configuration, session, scan input, or output failure |
+
+[Back to README](../README.md)

data/docs/rules-and-coverage.md

@@ -0,0 +1,158 @@
+# Rules and coverage
+
+| Rule | Severity | Purpose |
+| --- | --- | --- |
+| `abstract-reference` | hint | Ask what an abstract noun refers to |
+| `weak-predicate` | hint | Ask whether an operation's purpose or result is clear |
+| `contextual-phrase` | hint | Check whether a qualification changes interpretation or action; preserve necessary negation |
+| `generic-framing` | hint | Check whether an introduction or recap adds a claim, scope, or consequence |
+| `vague-degree` | hint | Ask what depth, level, scope, or comparison is intended |
+| `repeated-ending` | info | Identify three consecutive sentences with the same detected ending |
+| `glossary-variant` | warning | Identify project-specific terminology variants |
+| `style-candidate` | hint | Check selected polite/plain endings against an explicit style |
+
+MeCab mode matches noun and adjective tokens and dictionary forms of verbs.
+Sahen predicates are matched as a noun followed by `する` or the potential
+`できる`; standalone sahen nouns are not treated as verbal predicates. A configured
+sahen predicate takes precedence over a matching standalone noun rule. Auxiliary sequences retain
+negation, past tense, passive forms, and progressive forms in the reported surface.
+The added reach predicate is negative-only; the existing handling predicate is
+reviewed in both affirmative and negative forms. Glossary variants and generic
+framing phrases continue to use literal matching. Contextual phrases suppress
+overlapping morphological candidates. Except for the four predicate patterns
+described below, they use literal matching. Compound
+nouns are matched across adjacent noun tokens. Selection and narrowing verbs
+include potential forms; predicate surfaces also preserve causative auxiliaries.
+
+Default terms group components, actors, relationships, and resources under
+`abstract-reference`; operations under `weak-predicate`; and compressed noun
+relationships, referents, sufficiency, and negative qualifications under
+`contextual-phrase`. `木` and `余白` invite a context-dependent katakana terminology
+review, not mandatory replacement. `明示選択` and `欠落理由` invite checking whether
+`明示的選択` and `欠落した理由` clarify the intended relationship. Shared phrases such
+as `ではありません` cover longer qualifications without listing every sentence.
+`generic-framing` also flags `このように` and `要するに` as possible recaps.
+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;
+they do not add general inflection coverage or ban everyday verbs. Existing
+`木`, `持つ`, `書く`, `別です`, and `ではありません` rules cover related examples.
+The shared criteria explain context-dependent terminology, precise operations,
+direct predicates, and objective tone. They distinguish invocation from
+execution, configuration text from configuration changes, assumptions from
+requirements, and collecting errors from catching them. Suggested alternatives
+are not automatic replacement rules. Start a new review session to include
+updated rules and criteria; existing sessions retain their saved versions.
+
+Version 0.8.4 also configures `呼ぶ`, `読み取る`, `拾う`, and the sahen predicate
+`回収する` as weak-predicate candidates. MeCab matches their inflections for
+any object, including `指示と宣言を読み取ります` and `最後のdetailsを拾います`.
+This broadens review cues, not mandatory terminology changes; everyday and
+technically valid uses can be retained with a specific reason. Literal mode
+matches only the selected surfaces in the YAML. Longer contextual phrases take
+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
+phrase matching in both tokenizers; this is not complete inflection coverage or
+syntactic analysis. Bare verbs such as `効く`, `壊れる`, `溶かす`, and `倒す` are
+not added as general metaphor candidates. Identify the actual effect, policy,
+work, or failure state from evidence rather than applying a fixed replacement.
+Keep valid technical meanings and necessary negation.
+
+Version 0.6.2 additionally matches these four phrases with MeCab/IPADIC
+verb lemmas and adjacent predicate auxiliaries. For example, `地味に効かなかった`,
+`静かに壊れていた`, `時間を溶かしてしまった`, and `側に倒しました` retain their
+complete surfaces and polarity. A pattern is enabled only when its canonical
+phrase (`地味に効く`, `静かに壊れる`, `時間を溶かす`, or `側に倒す`) is present in
+the resolved `contextual-phrase.terms`. Removing those canonical entries from
+custom rules disables their morphological patterns; remaining exact surfaces
+still work. No YAML schema change is required. Allow lists accept the canonical
+phrase or exact detected surface. The most specific overlapping phrase wins,
+including allowed phrases. Masked inline content, unknown tokens, and paragraph
+boundaries cannot bridge a pattern. This remains a limited contextual heuristic,
+not a syntactic or semantic determination of metaphor. Literal mode retains
+exact surfaces and does not acquire this inflection coverage.
+
+In version 0.6.2, a `repeated-ending` candidate points to the ending
+of the third sentence in the first consecutive run within each paragraph.
+A sentence without a matching ending interrupts the run. The candidate remains
+informational because precise technical repetition can be necessary.
+
+The shared criteria distinguish reader instructions, actual system behavior,
+and available capabilities. They also separate readability from checks for
+missing information and unsupported additions. Sentence length, punctuation,
+and list density are contextual cues, not fixed acceptance thresholds. These
+updates are included in 0.6.2; start a new session to use updated criteria and rules.
+
+Literal term matching suppresses matches strictly contained in a longer matched
+term, across categories. The longer term also suppresses contained matches when
+it is allowed; separate occurrences remain candidates. Glossary and style checks
+are independent. In MeCab mode, predicates outside a contextual phrase can still
+be reported separately.
+
+Morphological candidates include `lemma`, `part_of_speech`, `negative`, and
+`detector` alongside the original `match`, line, and column. Negation detection
+covers common IPADIC negative auxiliaries; it is not full semantic analysis of
+negation scope or double negatives. Unknown tokens are not guessed. Kana/kanji
+variants of the alignment and gathering verbs have explicit canonical mappings;
+other spelling variants are not automatically normalized.
+
+The session records the MeCab version and dictionary file hashes. Verification
+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.
+
+Version 1.0.0 uses session schema 3.
+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-1.0.0
+```
+
+Severity describes review priority, not proof of an error. There is no AI-authorship
+score and no requirement to eliminate every match.
+
+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
+heuristic; review its diagnostics with care.
+
+Source locations are checked against original lines because Asciidoctor block
+locations can be inaccurate at include boundaries. If a location cannot be matched
+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.
+
+[Back to README](../README.md)

data/docs/scoring.md

@@ -0,0 +1,37 @@
+# Score an AsciiDoc manuscript
+
+Pass any AsciiDoc entry file directly; no review session or gold annotations are
+required. Output defaults to a short English report with a score out of 100.
+
+```sh
+asciidoc-pubkit review score book.adoc
+asciidoc-pubkit review score book.adoc --json --output score.json
+asciidoc-pubkit review score book.adoc --agent codex
+asciidoc-pubkit review score book.adoc --agent claude --json
+```
+
+Without `--agent`, the report shows a mechanical candidate-density indicator.
+With `--agent`, it shows a model readability rating and retains the mechanical
+score in JSON. See [How review and scoring work](architecture.md#how-review-and-scoring-work)
+for the analysis pipeline, formulas, and interpretation of these different scores.
+Successful scoring exits 0 regardless of the score; input, configuration,
+analyzer, evaluator, or output failures exit 2. No scoring mode establishes
+technical accuracy or meaning preservation; `meaning_verified` remains `false`.
+
+Scoring uses the same configuration discovery, custom rules, glossary, allows,
+style, language, base directory, include handling, and prose coverage as scanning.
+It accepts `--only`, `--config`, `--rules`, `--base-dir`, `--tokenizer`, `--style`,
+`--lang ja`, and repeated `--attribute` options. Excluded, unmapped, and protected
+blocks are not prose-scored. Coverage notices remain important when interpreting
+a score. MeCab/IPADIC is the default; literal mode must be selected explicitly.
+
+AI evaluation requires an installed, authenticated Codex or Claude CLI, and may
+send the selected paragraph text and headings to its configured provider and
+consume account usage. It receives no candidate findings or source file paths.
+`--model` selects the evaluator model, and `--timeout` sets the invocation timeout
+(default 300 seconds); both require `--agent`. Temporary evaluation files are
+removed after scoring. Use `--json --output FILE` to retain the result. Output
+files are never overwritten, and existing output is rejected before invoking an
+evaluator. A file with no unmasked prose is not sent to an evaluator.
+
+[Back to README](../README.md)