asciidoc-pubkit 0.9.0 → 1.0.1

data/docs/prose-evaluation.md

@@ -0,0 +1,246 @@
+# Prose evaluation
+
+Use a fixed set of Japanese technical paragraphs to compare detector or review
+criteria changes against a project-defined baseline. Keep detection performance,
+readability, and meaning preservation separate so that a clearer rewrite cannot
+hide a lost condition or invented fact.
+
+This guide describes the version 1.0.1 development checkout, including the
+`technical-prose-v2` corpus and criteria update. The evaluation runner is not an
+installed gem command. It does not measure Japanese naturalness or AI authorship
+as a single validated score.
+
+## Three different evaluations
+
+| Evaluation | Input and method | What the number means |
+| --- | --- | --- |
+| `review score` without `--agent` | A manuscript; candidate count normalized by unmasked prose length | Candidate-density indicator, not correctness or naturalness |
+| `script/evaluate-prose` without `--agent` | Fixed corpus and annotated targets; deterministic analysis | Detector precision, recall, F1, and location accuracy |
+| `script/evaluate-prose --agent codex` or `--agent claude` | Fixed corpus; generated review prompt, rewrite, and separate judge invocation | Readability and checklist preservation before and after rewriting |
+
+The default manuscript score is `max(0, 100 - 5 × candidates per 1,000 characters)`.
+A higher score means fewer detected candidates at that text length. Necessary
+repetition can still be a candidate, and fewer candidates alone do not establish
+better prose. See [Manuscript scoring](scoring.md) for the separate optional
+single-manuscript readability rating; that path has no original-versus-revision
+fact checklist.
+
+For a detector change, use the deterministic benchmark. For a writing or review
+criteria change, use the optional rewrite-and-judge trials to measure its effect
+on the actual revisions. Criteria can change while deterministic detector scores
+remain identical.
+
+## Fixed test data
+
+All examples are original project-authored editorial fixtures. They intentionally
+include patterns associated with generated prose, plus valid technical controls.
+They are not a collected dataset of known AI outputs or a representative sample
+of Japanese writing.
+
+| File | Contents and role |
+| --- | --- |
+| [prose_benchmark.ja.adoc](../test/fixtures/prose_benchmark.ja.adoc) | 21 paragraphs used as the actual AsciiDoc input |
+| [prose_benchmark.ja.json](../test/fixtures/prose_benchmark.ja.json) | Matching paragraph IDs and text, 11 annotated detector targets, and preservation checklists |
+| [prose_benchmark.yml](../test/fixtures/prose_benchmark.yml) | Fixed empty configuration that isolates the benchmark from discovered manuscript settings |
+| [prose_evaluation.ja.json](../test/fixtures/prose_evaluation.ja.json) | Detection examples and 20 manual revision pairs with expected `accept`, `reject`, or `needs-evidence` dispositions |
+
+The corpus includes framing such as `重要なのは`, metaphorical operations such
+as `地味に効く`, inflected and negative forms, and repeated endings. Controls
+include literal verbs, established technical terms, necessary repetition,
+concurrency requirements, and protected inline code.
+
+Eight paragraphs added in `technical-prose-v2` cover quantity targets, required
+order, modifier targets, condition scope, parallel checks, advice versus actual
+behavior, plain style, and punctuation and purpose scope. They have no additional
+detector targets but still reach the reviewer and judge. The checklists include
+explicit editorial constraints as well as technical facts.
+
+For example, this pair must be rejected even though its numeral is unchanged:
+
+| Original | Revision | Preservation issue |
+| --- | --- | --- |
+| 各ワーカーは最大3回再試行します。 | 全ワーカーで合計3回まで再試行します。 | A per-worker limit became an aggregate limit |
+
+Other revision pairs cover reversed recovery order, authentication conditions
+incorrectly extended to audit logging, independent checks made conditional, and
+an unsolicited change from plain to polite style. Acceptable pairs and unresolved
+cases prevent calibration from treating every change as an error.
+
+## What normal tests check
+
+Run the complete suite from the repository root with MeCab and UTF-8 IPADIC
+installed:
+
+```sh
+bundle exec rake test
+```
+
+[Prose benchmark tests](../test/prose_benchmark_test.rb) check exact agreement
+between the AsciiDoc input and JSON corpus, source mapping and paragraph order,
+annotated target positions, false positives and duplicates, and both MeCab and
+explicit literal analysis. They also check response validation, comparison
+compatibility, summary calculations, and mechanical verification in a trial
+using a fake evaluator. The fake evaluator makes the workflow test repeatable;
+it does not assess readability or understand the revision pairs.
+
+[Default rule tests](../test/default_rules_test.rb) check metaphor detection,
+allow lists, and protected text using the detection examples.
+[Writing tests](../test/writing_test.rb) and
+[review tests](../test/review_test.rb) check that the shared criteria reach writing
+prompts and saved review prompts. Existing sessions retain their saved criteria.
+
+Normal tests never invoke Codex or Claude. A passing suite establishes these
+contracts and regressions, not a measured improvement in model-generated prose.
+Literal-mode checks do not validate MeCab; there is no automatic fallback.
+
+## Establish a detector baseline
+
+Before changing the detector or review criteria, save a result on the fixed
+corpus. After the change, use a new output directory and compare it:
+
+```sh
+bundle exec ruby script/evaluate-prose --output .pubkit/evaluation/before
+# After changing the detector or review criteria:
+bundle exec ruby script/evaluate-prose --output .pubkit/evaluation/after \
+  --compare .pubkit/evaluation/before/report.json
+```
+
+The report scores only `generic-framing`, the four metaphorical-operation
+patterns, and `repeated-ending`. Other rule findings are counted separately.
+Detection matches a target's paragraph and kind. Location accuracy then checks
+its exact Unicode character offset; CLI source columns are one-based. A repeated
+ending target is at the matching ending of the third consecutive sentence.
+
+| Report field | Definition |
+| --- | --- |
+| `detection.precision` | Matched targets divided by detected scored candidates, × 100 |
+| `detection.recall` | Matched targets divided by annotated targets, × 100 |
+| `detection.f1` | 2 × matched targets divided by the sum of detected and annotated counts, × 100 |
+| `detection.location_accuracy` | Correctly located matches divided by all matched targets, × 100 |
+| `detection_delta` | After minus before for these four metrics, in percentage points |
+
+Duplicate detections count as false positives. Zero denominators are `null`, not
+perfect scores. A correctly detected candidate can still deserve a `keep`
+decision in contextual review.
+
+The historical [MeCab baseline](../benchmark/baseline-mecab.json) belongs to the
+original 13-paragraph `technical-prose-v1` corpus. Its precision was 100, recall
+81.818, F1 90, and location accuracy 77.778. Later detector fixes brought the
+11-target MeCab results to 100 for all four metrics; literal recall remained
+81.818. Keep that historical report unchanged. It cannot be compared directly
+with v2: create a new baseline after expanding the corpus.
+
+## Compare review criteria with AI trials
+
+First fix the corpus, calibration pairs, and judge rubric. Save an AI baseline
+before changing the review criteria, then change only the intended criteria and
+rerun under the same conditions:
+
+```sh
+bundle exec ruby script/evaluate-prose --agent codex --repeats 3 \
+  --output .pubkit/evaluation/ai-before
+# After changing only the review criteria:
+bundle exec ruby script/evaluate-prose --agent codex --repeats 3 \
+  --output .pubkit/evaluation/ai-after \
+  --compare .pubkit/evaluation/ai-before/report.json
+```
+
+These commands use each CLI's default model. For controlled comparisons, use
+`--model` and `--judge-model` to select fixed writer and judge models available
+in your environment. `--judge-agent` selects a separate evaluator CLI; otherwise
+the writer's CLI is used. Same-model judging can favor the writer's style.
+Claude trials use `--agent claude`. AI trials require MeCab; literal mode is
+available only for deterministic detector evaluation.
+
+Each trial performs these steps:
+
+1. Create a fresh review session and generate its actual saved review prompt.
+2. Supply the prompt and source checklists to the writer, requesting one JSON
+   paragraph per corpus ID. Faithful paragraphs can remain unchanged.
+3. Install revisions in the temporary trial manuscript and run mechanical
+   verification for scope, inline preservation, and structure.
+4. Invoke the judge separately with original and revised text labelled A/B,
+   alternating the order across trials. It receives source evidence but no
+   candidate findings or expected calibration answers.
+5. Summarize readability, checklist retention, additions, substitutions,
+   calibration, and mechanical verification separately.
+
+The writer receives evidence checklists, so the trial measures an
+evidence-assisted review workflow. It does not simulate every manuscript review.
+The judge sees original source evidence, so neutral labels reduce presentation
+bias without guaranteeing full blindness.
+
+## Read the AI results
+
+| Metric | Interpretation |
+| --- | --- |
+| `sentence_clarity` | Actors, actions, conditions, and sentence relationships are understandable |
+| `paragraph_coherence` | Sentences form a connected explanation |
+| `fact_retention` | Percentage of supplied checklist entries retained, including explicit editorial constraints |
+| `addition_free_paragraphs` | Percentage with no unsupported additions identified by the judge |
+| `substitution_free_paragraphs` | Percentage with no substitutions identified by the judge |
+| Calibration `accuracy` | Percentage of revision-pair dispositions matching the expected answers |
+| Calibration `balanced_accuracy` | Mean recall across `accept`, `reject`, and `needs-evidence` classes |
+| Mechanical verification pass rate | Percentage of trials passing the existing mechanical verifier |
+
+Readability is rated per paragraph on an ordinal scale: 1 means hard to
+understand, 2 means some ambiguity or distracting framing, and 3 means clear.
+Ratings are mapped to 0, 50, and 100 and averaged. These averages are descriptive
+summaries, not validated interval measurements. Inspect the paragraph reasons
+and actual revisions alongside the numbers.
+
+`ai.trials` contains each trial's `original`, `revision`, and `delta` metrics;
+`delta` is revision minus original. `ai.summary` retains means, population
+standard deviations, minima, and maxima. `ai_delta` compares these summary means
+between runs. In particular, `ai_delta.delta.sentence_clarity` compares the
+within-trial clarity improvement of the new run with that of the baseline.
+
+For an illustrative example, clarity of 50 before rewriting and 75 afterwards
+means a within-trial delta of +25. If the next run's delta is +30, the improvement
+relative to the baseline is +5 points. These are example numbers, not measured
+results. A readability gain with lower retention or new unsupported facts should
+not be accepted merely because it scores higher.
+
+One trial is a smoke test. Use at least three to inspect variation; the runner
+provides no significance test. Poor calibration warrants inspection before
+interpreting quality results. `meaning_verified` remains `false` regardless of
+scores or mechanical pass rate.
+
+## Comparison conditions and artifacts
+
+Comparisons require the same corpus, document, benchmark identity, scoring
+version, analyzer, and dictionary. Reports with configuration fingerprints also
+check the fixed configuration. AI comparisons additionally require matching
+judge rubric and calibration fingerprints, CLI versions, and actual reported
+writer and judge models. Missing actual model identity prevents AI comparison.
+
+Keep CLI user configuration consistent as well. Reports record criteria, rules,
+source, harness, and analyzer fingerprints, but a fingerprint cannot restore old
+content: retain the source revision and any uncommitted changes needed to
+reproduce the run. A changed corpus, judge rubric, or calibration set needs a
+new baseline. Compare the intended criteria or detector change only after the
+other evaluation conditions are fixed.
+
+AI trials require installed, authenticated local Codex or Claude CLIs. They may
+call their configured remote model providers and consume account usage. The
+runner uses argument arrays, read-only Codex execution or tool-disabled Claude
+execution, and a per-invocation timeout (`--timeout`, default 300 seconds).
+Missing CLIs, authentication failures, timeouts, and invalid responses fail
+explicitly. See [the adapter](../lib/asciidoc_pubkit/local_evaluator.rb) for the
+required flags; older CLIs may need an update.
+
+Outputs are saved under the chosen directory, including `report.json`, AI-mode
+`detection.json`, and per-trial review sessions, verification results, prompts,
+and evaluator responses. Existing output directories are never replaced.
+Partial artifacts remain after a failure. Keep results under ignored `.pubkit/`;
+do not commit private evaluation artifacts.
+
+For the version 1.0.1 yomiyasu v1.0.6 adaptation, the expanded v2 deterministic
+benchmark ran before and after the criteria change: precision, recall, F1, and
+location accuracy were all 100, with zero deltas. The suite passed 203 tests and
+2,552 assertions with real MeCab/IPADIC. These are detector and workflow checks.
+External AI rewrite-and-judge trials have not yet been run for this change, so
+its readability and preservation improvement remains unmeasured.
+
+[Development](development.md) · [Manuscript scoring](scoring.md) ·
+[Back to README](../README.md)

data/docs/references.md

@@ -0,0 +1,54 @@
+# 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. Applied
+  here: candidate findings feed a contextual review prompt, while phrases such as
+  `重要なのは` and `このように` invite inspection rather than automatic deletion.
+- [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. Applied here:
+  four limited metaphor patterns and third-sentence repetition locations inform
+  candidate detection; the shared criteria require evidence for concrete rewrites.
+  The 1.0.1 update adapts the structural comparison and sentence-function
+  guidance from [v1.0.6, commit 4075fc3](https://github.com/nanaism/yomiyasu/commit/4075fc34fb0333ca1fe42d32cd619338f4a138ba):
+  compare modifier and quantity targets, condition scope, parallel relationships,
+  and order before and after revision; preserve sentence function separately
+  from plain or polite style. The new examples are original project fixtures.
+  Markdown-specific bold fixes and numeric style thresholds are not imported.
+- [日本語技術文書の文章規範](https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d):
+  informs paragraph logic, evidence scope, and meaningful uncertainty. Applied
+  here: the shared criteria start from each paragraph's technical purpose and
+  preserve necessary conditions, uncertainty, and exact terminology.
+- [AI臭い文章とは何なのか](https://speakerdeck.com/nasuvitz/ai-kusai-bunshou-toha-nanina-no-ka):
+  provides examples of unnecessary contrast, abstract referents, and paired short
+  sentences. Applied here: the shared criteria ask reviewers to inspect these
+  patterns in context and recover concrete referents and connected explanations.
+
+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.
+  Applied here: the scoring rubric separates sentence clarity from paragraph
+  coherence, and the development judge evaluates fact retention independently.
+- [Evaluating Factuality in Text Simplification](https://aclanthology.org/2022.acl-long.506/)
+  (Devaraj et al., ACL 2022): distinguishes insertion, deletion, and substitution
+  errors. Applied here: development trials check each source fact and report
+  unsupported additions and substitutions separately; a readable rewrite can
+  still fail preservation review.
+- [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. Applied here: readability dimensions and preservation outcomes remain
+  separate in benchmark reports; the direct manuscript score makes no
+  preservation claim. SARI-style overlap metrics are not adopted.
+
+[Back to README](../README.md)

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)