asciidoc-pubkit 0.1.2 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de07af1758fdba08a7099b9e66f63b14084d0dad6cba8437498f0ddd0577b425
-  data.tar.gz: 8474d883c10c23f1221ff85cbd023d781c84f93dd55436a542c0d304c0a8f424
+  metadata.gz: c946ae67aae9ea8e6e21f5464b61daec42a18488c5aca5fbe434921f13dad824
+  data.tar.gz: 47ca9c1414c78699dbb07ebe3bfdb07460cc132a8a10c642392d147eb2247b90
 SHA512:
-  metadata.gz: 6983524a7967131b469360bebd417125d7eea14cdf8054d14c928940528d685ee50fd0c402ca354073a55e643217ed931ddda3ca3e402d252d02e4030b7b3a9e
-  data.tar.gz: 8e8111fea8d32dfb1449c48cfc8d8f2df22e58dec14a44a55c6dcb6596a6bd3e87aa86fbd596cfc332a6ca49c9d1452f5dd34b23126137d9359a081585e1ae56
+  metadata.gz: f8e1382976343a206f04363bdfb0896e3633605f239c2fbfb46afacaaf11415a93757a418c09d9fc449700742b15268f69883a36e0c7e200f9f3e73b4f4a0f22
+  data.tar.gz: 3f0395078d442df25b730cde44186cb1868c3b68f7ea292438a2ad8871179a30198524fcd846c5ea6f2ce84d65d90f01b9d4db829f012b6e47e68f4b2051d3da

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.1 — 2026-10-01
+
+- Add `review score FILE` for direct AsciiDoc manuscript scoring without a
+  session. Report a candidate-density indicator by default and optionally invoke
+  a local Codex or Claude CLI for readability ratings with `--agent`. Preserve
+  manuscript files, coverage limits, explicit tokenizer selection, and
+  `meaning_verified: false`.
+- Add a development-only prose benchmark with a fixed AsciiDoc corpus, scored
+  candidate coverage and locations, and a saved MeCab baseline before detector
+  changes. Keep quality judgments separate from detection performance.
+- Add explicit local Codex/Claude rewrite and judge trials with fact checklists,
+  blinded document labels, evaluator calibration, repeated-run statistics, and
+  compatibility checks for baseline comparisons. Keep benchmark AI trials
+  separate from manuscript scoring and the default test suite.
+
+- Extend the shared Japanese prose criteria with evidence-based metaphor review,
+  distinctions between instructions, behavior, and capabilities, and separate
+  checks for information loss and unsupported additions.
+- Add limited metaphorical-operation phrases as contextual review candidates,
+  with a Japanese evaluation corpus for detection and manual meaning review.
+- Introduce yomiyasu in the README references.
+
+## 0.6.0 — 2026-09-30
+
+- 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
+  both. Reject unsupported languages explicitly, including document attributes.
+- Save the shared criteria and language with each review session, and update the
+  book writing and review skills to use the generated prompts.
+- 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
+  allow-list handling, and recognize sahen potential forms before noun rules.
+- Reduce single-file review prompts by emitting each paragraph once, sharing
+  context metadata, and compacting JSON; retain all candidates and review settings.
+- Confirm replacement of existing review sessions in interactive scans.
+- 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.

data/README.md

@@ -5,25 +5,38 @@
 
 # asciidoc-pubkit
 
-A toolkit for authoring, reviewing, and publishing AsciiDoc books.
+A toolkit for authoring and reviewing AsciiDoc books.
 
-The initial release reviews Japanese running prose, generates contextual review
-prompts for coding agents, and checks edited manuscripts against a saved baseline.
+Version 0.6.1 provides shared Japanese technical writing criteria, an authoring
+prompt, contextual review prompts, manuscript scoring, and baseline verification
+for edited manuscripts.
 The CLI, diagnostics, documentation, and generated instructions are in English.
 Japanese text is retained in manuscript excerpts, rule dictionaries, and fixtures.
 
 ## Status
 
-This is an initial implementation. It does not invoke an AI service, automatically
-rewrite manuscripts, or publish books. EPUB, image, and book scaffolding commands
-are planned extensions, not available features.
+The CLI does not automatically rewrite manuscripts or 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.
 Starting with version 0.1.1, the default review backend requires the external MeCab
 command and a UTF-8 IPADIC dictionary. Node.js and textlint are not required.
 Explicit `--tokenizer literal` mode provides limited phrase matching without MeCab.
 
-Version 0.1.1 includes morphological analysis. Version 0.1.0 uses literal matching.
+Version 0.6.1 also provides `review score FILE` for a manuscript score.
+It uses local candidate analysis by default; `--agent codex` or `--agent claude`
+explicitly asks an installed CLI to evaluate readability and may connect to its
+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`.
+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
+support. Other languages are reserved for future implementations and now
+return an explicit error. A review session saves its language and the criteria
+used to generate its prompt.
 
 ## Install from RubyGems
 
@@ -39,6 +52,13 @@ Ruby 3.2 or later is required. RubyGems installs the required Ruby dependencies;
 no repository clone or Node.js installation is needed. MeCab and IPADIC must be
 installed separately when using version 0.1.1 or later in the default mode.
 
+Generate a writing prompt without an existing manuscript:
+
+```sh
+asciidoc-pubkit writing criteria --lang ja
+asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
+```
+
 Run the review workflow from your manuscript directory:
 
 ```sh
@@ -60,7 +80,7 @@ Add the gem to your project's `Gemfile` to manage its version with Bundler:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'asciidoc-pubkit', '~> 0.1.2'
+gem 'asciidoc-pubkit', '~> 0.6.1'
 ```
 
 Then install dependencies and run the CLI through Bundler:
@@ -82,17 +102,88 @@ git clone https://github.com/cybergarage/asciidoc-pubkit.git
 cd asciidoc-pubkit
 bundle install
 gem build asciidoc-pubkit.gemspec
-gem install ./asciidoc-pubkit-0.1.2.gem
+gem install ./asciidoc-pubkit-0.6.1.gem
 asciidoc-pubkit --version
 ```
 
 The gem name and CLI name are `asciidoc-pubkit`; the Ruby require path is
 `asciidoc_pubkit`, and the namespace is `AsciidocPubkit`.
 
+## Writing commands
+
+`writing criteria` prints the packaged common criteria. `writing prompt` adds
+task instructions around those same criteria. Neither command needs an AsciiDoc
+file, a review session, MeCab, or network access. Both accept `--lang ja` and
+`--output FILE`; output defaults to stdout, and an existing output file is never
+overwritten. The prompt asks the agent to read project instructions and evidence;
+it does not supply source facts or authorize edits. Book-specific voice and
+format still come from the book. The OSS-only prose style profile remains with
+the book workflow, not the shared default.
+
+```sh
+asciidoc-pubkit writing criteria --lang ja
+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.1.
+
 For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
 paragraphs deliberately contain review candidates; its code block must remain
 unchanged.
 
+## 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`, `candidate-density-v1` reports a mechanical review indicator:
+`max(0, 100 - 5 * candidates * 1000 / characters)`, rounded to three decimals.
+Characters are non-whitespace Unicode characters in source-mapped running prose
+after inline masking. Every finding, including informational candidates, counts
+once. Lower scores indicate more detected review cues per 1,000 characters, not
+proven defects or AI authorship. Short texts are especially sensitive to a single
+candidate. No unmasked prose yields `null` rather than a perfect score.
+Successful scoring exits 0 regardless of the score; invalid input, configuration,
+analyzer, evaluator, or output failures exit 2. Verification exit codes are
+unchanged. The JSON report includes candidate counts, findings, coverage notices,
+analysis identity, and the formula. Rule, allow-list, and tokenizer changes can
+change the score even when the manuscript is unchanged.
+
+With `--agent`, `llm-readability-v1` displays an evaluator score instead. Sentence
+clarity and paragraph coherence are each rated 1–3 per paragraph and mapped to
+0, 50, and 100. The displayed score averages these two dimensions across scored
+paragraphs with equal paragraph weights. JSON also retains the individual
+ratings, English reasons, source locations, evaluator model and CLI version,
+rubric fingerprint, and the mechanical candidate-density score. These ordinal
+averages are descriptive summaries, not validated interval measurements. This
+single-document evaluation has no reference manuscript or evidence checklist;
+it does not measure fact retention, technical accuracy, or meaning preservation.
+`meaning_verified` remains `false` in both modes.
+
+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.
+
 ## Run from a local checkout
 
 Use the `run` Make target to execute the checkout without installing the
@@ -163,7 +254,7 @@ asciidoc-pubkit review verify .pubkit/review --output verification.json
 ```
 
 All three commands leave manuscript files unchanged. Only the agent edits them.
-Output paths must not already exist. Use a new session directory for a new pass.
+`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.
 
@@ -175,6 +266,27 @@ 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
@@ -213,13 +325,24 @@ asciidoc-pubkit review prompt .pubkit/review --mode diagnose
 for findings and proposed revisions without editing. Both modes require the agent
 to distinguish **revise**, **keep**, and **needs-evidence** decisions.
 
-The Markdown includes every selected paragraph, neighboring selected paragraphs,
-heading context, candidates, saved settings, and preservation instructions. It
-also asks for contextual review of paragraphs with no machine matches. Initial
+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
 
@@ -297,16 +420,17 @@ use an absolute path for an explicit executable override.
 | --- | --- | --- |
 | `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 | Review referents, assumptions, and qualifications while preserving negation |
-| `generic-framing` | hint | Review generic introductions and emphasis |
+| `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 the verb for "do"; standalone
-sahen nouns are not treated as verbal predicates. Auxiliary sequences retain
+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
@@ -315,6 +439,39 @@ literal matching and suppress overlapping morphological candidates. 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.
+
+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.
+
+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.1; 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
@@ -327,12 +484,12 @@ reports analyzer changes instead of treating results from different dictionaries
 as directly comparable. Prompt generation uses saved evidence and does not need
 MeCab. Changed rules or dictionary settings require a new scan.
 
-Sessions from earlier tool versions are not compatible with 0.1.2. Keep the original baseline for
+Sessions from earlier tool versions are not compatible with 0.6.1. 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.1.2
+asciidoc-pubkit review scan book.adoc --output .pubkit/review-0.6.1
 ```
 
 Severity describes review priority, not proof of an error. There is no AI-authorship
@@ -365,11 +522,121 @@ analysis of inflections, negative predicates, Unicode positions, and long lines.
 Install MeCab and UTF-8 IPADIC before running the complete test suite.
 GitHub Actions is configured for Ruby 3.2, 3.3, 3.4, and 4.0 on Linux.
 
-## License
+[`test/fixtures/prose_evaluation.ja.json`](test/fixtures/prose_evaluation.ja.json)
+contains original Japanese technical prose for candidate regression and manual
+revision evaluation. Automated tests check metaphor candidates in both
+tokenizers, source positions, inline exclusions, and allow lists. The revision
+pairs are manual evaluation cases, not an automated semantic checker or a
+measured AI benchmark. Compare source and revision separately for readability,
+information loss, and unsupported additions, using each case's review axes and
+expected disposition. Cover conditions, negation, numbers, versions, actors,
+causes, implementation requirements, and necessary repetition. Record the
+model, prompt, source evidence, and human judgments when evaluating actual
+generated revisions; fewer findings alone do not establish an improvement.
+
+### Development prose benchmark
+
+The checkout provides `script/evaluate-prose` for measuring future detector and
+prompt changes. This is a development tool, not an installed gem command; the
+benchmark CLI calls are separate from the optional `review score --agent` path.
+The fixed
+[`prose_benchmark.ja.adoc`](test/fixtures/prose_benchmark.ja.adoc) contains 13
+original editorial paragraphs with intentionally vague framing and metaphors,
+inflection variants, and valid technical prose controls. Its
+[`annotations`](test/fixtures/prose_benchmark.ja.json) contain 11 review targets
+and separate source fact checklists. It is a small synthetic regression corpus,
+not an AI authorship dataset or a representative measure of prose quality.
+
+Run the deterministic benchmark before and after a change:
 
-Copyright 2026 CyberGarage.
+```sh
+bundle exec ruby script/evaluate-prose --output .pubkit/evaluation/before
+# After changing the detector or prompt:
+bundle exec ruby script/evaluate-prose --output .pubkit/evaluation/after \
+  --compare .pubkit/evaluation/before/report.json
+```
 
-Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
+The report measures candidate precision, recall, F1, and location accuracy on a
+0–100 scale for `generic-framing`, metaphorical operations, and `repeated-ending`.
+Other rule findings are counted separately and are not judged against these
+annotations. Detection matches a target's paragraph and kind; location accuracy
+then checks the one-based source position, represented internally as a zero-based
+Unicode character offset within that paragraph. The annotated repeated-ending
+location is the matching ending of the third sentence in the consecutive run.
+A candidate can be correctly detected even when the reviewer should keep it.
+Zero denominators are reported as `null`, not perfect scores. Duplicate detections
+count as false positives. These scores measure the detector, not the manuscript.
+
+The checked-in [`MeCab baseline`](benchmark/baseline-mecab.json), captured before
+the planned detector changes, has precision 100, recall 81.818, F1 90, and location
+accuracy 77.778. It misses two inflected metaphor phrases and mislocates two
+repeated-ending candidates. Reports record source, criteria, rules, corpus, and
+dictionary fingerprints. Comparisons reject changed corpora, scoring versions,
+analyzers, or dictionaries. Reports with configuration fingerprints also reject
+changed benchmark configuration. A fixed empty configuration
+keeps these trials independent of auto-discovered manuscript settings.
+Record your own baseline when dictionary fingerprints
+differ. `--tokenizer literal` explicitly selects a separate limited-mode run;
+there is no automatic fallback, and literal results do not validate MeCab.
+
+### Optional local AI evaluation
+
+Use an installed, authenticated Codex or Claude CLI to perform rewrite and judge
+trials explicitly. A local CLI may call its configured remote model provider and
+consume account usage; this is not an offline model test. Normal `rake test`
+does not run either CLI. For example:
+
+```sh
+bundle exec ruby script/evaluate-prose --agent codex --repeats 3 \
+  --output .pubkit/evaluation/ai-before
+bundle exec ruby script/evaluate-prose --agent codex --repeats 3 \
+  --output .pubkit/evaluation/ai-after \
+  --compare .pubkit/evaluation/ai-before/report.json
+# Or use Claude:
+bundle exec ruby script/evaluate-prose --agent claude \
+  --output .pubkit/evaluation/claude-before
+```
+
+Each trial generates the actual saved review prompt, requests paragraph revisions
+as JSON, and runs the existing mechanical verifier. A fresh judge invocation
+evaluates both original and revised prose with neutral A/B labels, alternating
+their order across trials. The judge sees source evidence but no findings, tool
+revision labels, or expected calibration answers. The writer receives the source
+fact checklist in addition to the review prompt, so this measures an evidence-
+assisted workflow rather than every real-world manuscript review.
+
+Sentence clarity and paragraph coherence are separately rated 1–3 and displayed
+as 0, 50, or 100 before averaging. These ordinal averages are descriptive
+summaries, not validated interval measurements. Fact retention measures the
+percentage of annotated source facts preserved; addition-free and substitution-
+free paragraph percentages remain separate. Known acceptable, incorrect, and
+unsupported revisions from `prose_evaluation.ja.json` calibrate the judge using
+accuracy and balanced accuracy across the three dispositions. Inspect poor
+calibration before interpreting quality scores. No combined AI-likeness score or
+semantic pass is produced: `meaning_verified` remains `false`.
+Mechanical verification results and their pass rate are also reported separately.
+Quality scores from a trial with preservation violations remain visible for
+diagnosis; a completed evaluation does not authorize accepting that revision.
+
+One trial is a smoke test; use at least three to inspect variation. Reports retain
+individual scores, means, population standard deviations, and ranges. They do
+not perform a significance test. Same-model judging can favor the writer's style;
+`--judge-agent` and `--judge-model` select a separate evaluator. `--model` selects
+the writer model; omitted model options use each CLI's default. AI comparisons
+require the same reported writer and judge models, CLI versions, rubric, and
+calibration corpus. CLI defaults can change, so retain the recorded model IDs
+and use explicit model options for controlled comparisons. Score changes can
+reflect sampling variation as well as implementation changes.
+
+The runner uses argument arrays rather than shell interpolation, read-only Codex
+execution or tool-disabled Claude execution, and a per-invocation timeout
+(`--timeout`, default 300 seconds). The CLI may still load its user configuration;
+use consistent settings for comparisons. Current adapters require the flags
+shown by `codex exec --help` and `claude --help`; older CLI versions may need an
+update. Missing CLIs, authentication errors, timeouts, and malformed responses
+fail explicitly. Existing output directories are never replaced. Partial
+artifacts remain available after failures. Results, prompts, responses, and review
+sessions belong under ignored `.pubkit/`; do not commit private evaluation runs.
 
 ## Customize review rules
 
@@ -411,7 +678,7 @@ rejected. YAML aliases and object tags are not supported.
 | `schema_version` | Integer `1` |
 | `terms` | Mapping containing all five categories listed below |
 | `verbs` | Mapping from canonical verb forms to nonempty arrays of MeCab/IPADIC dictionary forms; each dictionary form belongs to only one canonical form |
-| `sahen` | Array of nouns matched with a following `する` verb |
+| `sahen` | Array of nouns matched with a following `する` or potential `できる` verb |
 | `negative_only` | Array of canonical predicates restricted to negative forms; use the noun plus `する` for sahen predicates |
 | `compound_nouns` | Array of terms matched across contiguous noun tokens; each must also appear in `abstract-reference.terms` |
 
@@ -436,3 +703,47 @@ Prompt generation and verification use the saved contents, even if the original
 YAML file is subsequently edited or removed. Start a new session to apply rule
 changes. Older sessions without a rule snapshot fall back to the currently
 installed default file; start a new session for reproducible custom-rule reviews.
+
+## References
+
+The shared criteria and default questions draw on the following editorial
+sources. Their stylistic choices differ, including whether headings should state
+conclusions. Candidate detection therefore leaves contextual judgment, document
+structure, and final edits to the reviewer.
+
+- [natural-japanese](https://github.com/coji/natural-japanese): separates mechanical
+  detection from contextual judgment and identifies repetitive framing.
+- [yomiyasu](https://github.com/nanaism/yomiyasu):
+  informs evidence-based review of
+  metaphorical operations, distinctions between instructions and capabilities,
+  and separate assessment of meaning preservation and readability. The criteria
+  and regression examples here are independently written; the upstream skill,
+  Python linter, and benchmark passages are not bundled. Fixed style thresholds
+  and an AI-likeness score are not adopted.
+- [日本語技術文書の文章規範](https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d):
+  informs paragraph logic, evidence scope, and meaningful uncertainty.
+- [AI臭い文章とは何なのか](https://speakerdeck.com/nasuvitz/ai-kusai-bunshou-toha-nanina-no-ka):
+  provides examples of unnecessary contrast, abstract referents, and paired short
+  sentences.
+
+The development evaluation adapts ideas from the following primary research;
+its engineering audience, corpus, and rubric do not reproduce those benchmarks.
+Research texts and datasets are not redistributed here.
+
+- [Evaluation of Document-Level Text Simplification in Japanese](https://aclanthology.org/2026.lrec-1.85/)
+  (Yamashita et al., LREC 2026): separates information preservation from sentence
+  and document simplicity and evaluates LLM judgments against human annotations.
+  Its elementary-school audience and Wikipedia corpus differ from this project.
+- [Evaluating Factuality in Text Simplification](https://aclanthology.org/2022.acl-long.506/)
+  (Devaraj et al., ACL 2022): distinguishes insertion, deletion, and substitution
+  errors, motivating separate checks for unsupported additions and lost facts.
+- [Evaluating Document Simplification: On the Importance of Separately Assessing Simplicity and Meaning Preservation](https://aclanthology.org/2024.readi-1.1/)
+  (Cripwell et al., READI 2024): motivates separate readability and preservation
+  scores rather than a single aggregate. SARI-style overlap metrics are not
+  adopted because lexical agreement alone is insufficient for this prose review.
+
+## License
+
+Copyright 2026 CyberGarage.
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).