kotonoha 0.1.4 → 0.1.5-dev.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add a guarded Japanese prose-optimization handoff to `natural-japanese` or
+  an equivalent registered skill, with invariant preservation, bounded
+  convergence, structural revalidation, and explicit completion statuses.
+
 ## [0.1.4] - 2026-09-29
 
 ### Added

package/README.md

@@ -15,11 +15,12 @@ specification, and handoff for a dedicated PPTX creation skill.
 
 Technical documents tend to have two separate problems: "is the prose
 natural" and "does the structure have the right amount of information".
-`tech-writer` specializes in the latter, leaving the former (sentence-level
-naturalness, removing "AI smell") to a prose-polishing skill such as
+`tech-writer` specializes in the latter and delegates the former
+(sentence-level naturalness, reading load, terminology, and removing
+"AI smell") to a prose-polishing skill such as
 [natural-japanese](https://github.com/coji/natural-japanese). With both
-installed, lock down the structure with `tech-writer` first, then polish
-Japanese prose with natural-japanese.
+installed, kotonoha locks the structure and technical invariants, invokes the
+Japanese prose pass, then rechecks the structure before rubber-duck review.
 
 ## What it does
 
@@ -29,6 +30,9 @@ Japanese prose with natural-japanese.
   operations runbooks, migration plans, security designs, technical proposals,
   RFI/RFP procurement documents, and Qiita/Zenn articles
 - Doctype-specific structure and checklists to guide writing
+- Optional `natural-japanese` integration for Japanese phrase lint,
+  reading-load review, terminology checks, and iterative prose optimization
+  without changing IDs, facts, tables, code, or acceptance criteria
 - Iterative rubber-duck review after document creation, with fixes and
   re-review until no actionable findings remain; unavailable reviews are
   reported as `review not performed`, while unresolved review loops are
@@ -92,6 +96,8 @@ guidance and a review checklist under
 - GitHub Copilot CLI installed
 - Python 3.9+ if you want to run the lint script (standard library only,
   no extra install needed)
+- `uv` when using `natural-japanese` diagnostics such as phrase lint,
+  reading-load analysis, outline extraction, and terminology checks
 
 ### Install from npm
 
@@ -103,6 +109,25 @@ npm install --save-dev kotonoha
 npx kotonoha install
 ```
 
+For Japanese sentence-level optimization, also install
+`natural-japanese` using one of its supported installation methods:
+
+```bash
+npx skills add coji/natural-japanese
+```
+
+Ensure the installed skill is visible to Copilot CLI in the same registered
+skill root used by this project, such as
+`.github/skills/natural-japanese` or
+`~/.copilot/skills/natural-japanese`. If the command installs it for a
+different host, follow the upstream alternative installation instructions
+and place or link the skill into a Copilot-visible skill directory.
+
+If no compatible Japanese prose-polishing skill is registered, kotonoha
+finishes the structural workflow and reports
+`Japanese prose optimization not performed` instead of claiming that the
+prose was optimized.
+
 The default destinations are `.github/skills/tech-writer` and
 `.github/skills/presentation-planner` in the current project. To install
 only one skill, or use another supported skill directory:
@@ -188,7 +213,8 @@ skills/presentation-planner/ # storyline, design-spec, and PPTX handoff skill
 
 - `scripts/lint.py` only detects structural issues (headings, code blocks,
   placeholders, links); it does not detect prose naturalness, vocabulary,
-  or rhythm.
+  or rhythm by itself. Those checks require a registered prose-polishing
+  skill such as `natural-japanese`.
 - The doctypes are written mainly with Japanese technical-writing
   conventions in mind; most of the guidance (especially the commit-message
   imperative-mood rule) applies directly to English documents as well.

package/bin/npm-publish-tag.js

@@ -0,0 +1,12 @@
+"use strict";
+
+function publishTagForVersion(version) {
+  return version.includes("-") ? "next" : "latest";
+}
+
+if (require.main === module) {
+  const { version } = require("../package.json");
+  process.stdout.write(`${publishTagForVersion(version)}\n`);
+}
+
+module.exports = { publishTagForVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotonoha",
-  "version": "0.1.4",
+  "version": "0.1.5-dev.0",
   "description": "GitHub Copilot CLI skills for technical writing and PPTX presentation planning.",
   "license": "MIT",
   "author": "nahisaho",

package/skills/tech-writer/SKILL.md

@@ -25,13 +25,12 @@ description: >-
   the request is a bare goal without enough context to start (e.g. "I want
   to write a README" / "○○を書きたい"), since this skill drives a one
   question-at-a-time intake before writing. Supports both Japanese and
-  English documents, with Japanese as the primary target for polished,
-  natural phrasing (pairing well with https://github.com/coji/natural-japanese
-  for sentence-level Japanese refinement). Does NOT handle sentence-level
-  naturalness, word choice, or rhythm ("AI smell" removal) — that is the
-  domain of natural-japanese and similar prose-polishing skills. This skill
-  is specific to a document's structure, information completeness, and
-  reader fit.
+  English documents, with Japanese as the primary target. Owns document
+  structure, information completeness, and reader fit; for living Japanese
+  documents, it orchestrates a registered prose-polishing skill such as
+  https://github.com/coji/natural-japanese for sentence-level naturalness,
+  word choice, rhythm, and "AI smell" removal without reimplementing that
+  skill.
 license: MIT
 argument-hint: "[write|review|score] [doctype] <target file or request>"
 ---
@@ -58,11 +57,13 @@ reference files.
 
 Document quality splits into two layers: "is the structure right" and "is
 the prose natural and readable". This skill owns the first layer (structure,
-document type conventions, completeness, reader fit). The second layer
-(sentence-level naturalness, removing "AI smell", rhythm) is out of scope and
-belongs to a prose-polishing skill such as [natural-japanese](https://github.com/coji/natural-japanese).
-When both skills are installed, use this skill to lock down the structure
-first, then hand Japanese prose to natural-japanese for polish.
+document type conventions, completeness, reader fit). A prose-polishing skill
+such as [natural-japanese](https://github.com/coji/natural-japanese) owns the
+second layer (sentence-level naturalness, removing "AI smell", rhythm);
+tech-writer orchestrates that skill without duplicating its rules or scripts.
+When both skills are installed, this skill locks down the structure and
+orchestrates the §5 handoff to natural-japanese during `write` mode before
+the final rubber-duck review.
 
 - Rule of thumb: "does removing a heading still make sense?" tests structure
   (this skill's job). "Does rereading a single sentence change its meaning?"
@@ -75,12 +76,14 @@ first, then hand Japanese prose to natural-japanese for polish.
 Infer the mode from the argument or the request:
 
 - `write` (default): new document, or restructuring a draft. Runs the full
-  §1–§5 workflow, starting with the intake loop in §1 and ending only after
+  §1–§6 workflow, starting with the intake loop in §1 and ending only after
   the rubber-duck review loop has no remaining actionable findings. If an
   independent review cannot run or cannot converge, returns the explicit
-  review status required by §5 instead of claiming a clean review.
+  review status required by §6 instead of claiming a clean review. For a
+  in-scope Japanese living document, also return the §5 Japanese prose
+  optimization status.
 - `review`: structural review of an existing document. Does not rewrite;
-  reports the gap against the doctype checklist (§6).
+  reports the gap against the doctype checklist (§7).
 - `score`: structure-only quick diagnostic. Runs
   `scripts/lint.py --json <file>` and summarizes the findings (no rewrite).
 
@@ -137,7 +140,7 @@ hand the user a checklist to fill in. Instead:
    one-line note) and move on.
 6. **Once complete, do not ask the user to compose anything.** Synthesize
    the gathered answers into the best possible generation approach yourself
-   and immediately continue into §2–§5 in the same turn to produce the
+   and immediately continue into §2–§6 in the same turn to produce the
    document. Skip further confirmation unless the doctype is release-facing
    and consequential (e.g. a public release note with breaking changes) or
    the user explicitly asked to see a plan first.
@@ -229,11 +232,11 @@ or `references/doctypes/release-notes.md` instead — see the scope note in
 verbatim there.
 
 Sentence-level concerns — keeping individual sentences concise, avoiding
-double negatives, not dropping the subject, and general naturalness — are
-out of this skill's scope regardless of doctype. When natural-japanese (or
-an equivalent prose-polishing skill) is available, hand Japanese prose to
-it for that pass; otherwise apply ordinary careful-writing judgment, but
-don't treat it as this skill's responsibility to enforce.
+double negatives, not dropping the subject, and general naturalness — belong
+to a prose-polishing skill. In `write` mode for a Japanese document, perform
+the explicit handoff in §5 after the structure is complete. If no compatible
+optimizer is available, still apply ordinary careful-writing judgment and
+report the missing optimization pass explicitly.
 
 
 ## 4. Review — structural check
@@ -262,9 +265,60 @@ step 2 as the primary check for those.
 4. **Reader-goal recheck**: confirm the "what the reader can do after
    reading" outcome from §1 is actually achievable from this document alone.
 
-## 5. Rubber-duck review loop — write mode only
-
-After the structural review in §4, use the host's subagent mechanism to
+## 5. Optimize Japanese prose without changing the structure — write mode only
+
+For a living, multi-section document whose requested final language is
+Japanese, read
+`references/japanese-prose-optimization.md` and hand the completed draft to a
+registered `natural-japanese` or equivalent Japanese prose-polishing skill.
+This pass is mandatory when such a skill is available.
+
+Treat the optimizer as available when the host's registered skill list
+contains `natural-japanese` or a compatible Japanese prose-polishing skill.
+Invoke it through the host's skill-loading mechanism; when only installed
+skill files are exposed, check
+`.github/skills/natural-japanese/SKILL.md`,
+`.copilot/skills/natural-japanese/SKILL.md`, and
+`$HOME/.copilot/skills/natural-japanese/SKILL.md`, then load the discovered
+`SKILL.md` and follow that workflow. Treat the pass as unavailable only when
+no compatible registration or readable skill installation exists, or when
+the optimizer cannot start.
+
+Freeze heading hierarchy, section order, identifiers, numeric facts,
+citations, normative language, tables, code, commands, acceptance criteria,
+and explicit risks before handoff. Require sentence-level optimization and
+request AI-pattern diagnostics, reading-load review, and terminology checks
+when their scripts are runnable, without changing those invariants. Missing
+optional diagnostics are a reported limitation, not proof that the prose pass
+did not run. After the prose pass, repeat the doctype checklist and structural
+lint from §4.
+
+For an in-scope Japanese document in `write` mode, report one explicit status.
+Do not run this pass or report a status for atomic artifacts such as commit
+messages, PR descriptions, issue reports, single release-note entries, or
+code comments/docstrings unless the user explicitly requests prose polishing
+and supplies the prose in a standalone file:
+
+- `Japanese prose optimization completed`
+- `Japanese prose optimization not performed`
+- `Japanese prose optimization did not converge`
+
+Across the complete write workflow, allow at most 15 optimizer handoffs,
+including reruns after rubber-duck edits. If no compatible optimizer can be
+loaded, use
+`Japanese prose optimization not performed` and state the reason. If the
+optimizer starts but fails, or an edit violates a frozen invariant, revert
+the invalid edit and retry within the three-round limit; unresolved failures
+or invariant violations use
+`Japanese prose optimization did not converge`. Do not claim this
+optimization from kotonoha's structural lint alone. Documents that are not
+within the Japanese final-language scope defined above require no optimization
+status.
+
+## 6. Rubber-duck review loop — write mode only
+
+After the structural review in §4 and any Japanese prose optimization in §5,
+use the host's subagent mechanism to
 launch an independent reviewer in the `rubber-duck` role to challenge the
 completed document for meaningful problems that the authoring pass may have
 missed. Prefer a registered `rubber-duck` agent when the host provides one;
@@ -282,9 +336,14 @@ for `write` mode; do not run it for `review` or `score` mode.
 2. **Resolve every valid finding**: edit the document rather than merely
    listing proposed fixes. If a finding conflicts with a stated requirement
    or is factually inapplicable, record a one-line reason for declining it.
-3. **Re-run the relevant checks after each edit round**: repeat the doctype
-   checklist and structural lint from §4 before asking for another
-   rubber-duck review. A fix must not introduce a new structural defect.
+3. **Re-run the relevant checks after each edit round**: if a fix changed
+   Japanese prose, repeat the §5 optimization over the changed prose before
+   reporting its final status. Then repeat the doctype checklist and
+   structural lint from §4 before asking for another rubber-duck review. A
+   fix must not introduce a new structural defect or leave the final Japanese
+   prose outside the completed optimization pass. If a required rerun cannot
+   start because all 15 handoffs were already used, or cannot complete,
+   report `Japanese prose optimization did not converge`, not `completed`.
 4. **Review again with the prior decisions**: reuse the same reviewer context
    when supported. Otherwise, include the previous findings, applied fixes,
    and declined findings with their reasons in every new review prompt. Ask
@@ -306,7 +365,7 @@ for `write` mode; do not run it for `review` or `score` mode.
    contradictory requirements, label it `review did not converge` and
    include the latest unresolved findings and fixes already attempted.
 
-## 6. Doctype checklist summary
+## 7. Doctype checklist summary
 
 See each reference file for detail. The items below are for living,
 multi-section documents (README, design doc, API reference, release notes,
@@ -333,5 +392,6 @@ The idea of separating structure from prose comes from
 [natural-japanese](https://github.com/coji/natural-japanese) (MIT License)
 and its design principle "machines detect, humans (or agents) judge" and
 "prevent at generation time rather than fix afterward". This skill extends
-that separation to the structural side of technical documents, deliberately
-leaving prose naturalness out of scope.
+that separation by owning technical-document structure while orchestrating,
+but not reimplementing, the registered prose-polishing skill responsible for
+sentence-level naturalness.

package/skills/tech-writer/references/japanese-prose-optimization.md

@@ -0,0 +1,108 @@
+# Japanese prose optimization handoff
+
+Use this pass after a Japanese document's structure and required information
+are complete. The goal is to remove mechanical or translated-sounding prose
+without changing the document's approved meaning, obligations, evidence, or
+traceability.
+
+The preferred optimizer is the
+[natural-japanese prose-polishing skill](https://github.com/coji/natural-japanese).
+Kotonoha owns document structure and completeness; `natural-japanese` owns
+sentence-level clarity, rhythm, word choice, reading load, and detection of
+repeated AI-like phrasing.
+
+## Run this pass when
+
+- The requested final language is Japanese, including a bilingual document
+  whose audience-facing prose is primarily Japanese.
+- The task is `write` mode.
+- The artifact is a living, multi-section document.
+- A registered `natural-japanese` or equivalent Japanese prose-polishing
+  skill is available.
+
+Skip it for English documents, generated machine-readable files, and source
+code. Also skip atomic artifacts such as commit messages, PR descriptions,
+issue reports, single release-note entries, and code comments/docstrings
+unless the user explicitly requests prose polishing and supplies the prose in
+a standalone file. For in-scope mixed-language documents, optimize only
+Japanese prose.
+
+## Freeze these invariants
+
+Give the prose optimizer the target file, doctype, reader, and intended
+outcome. Require it to preserve:
+
+- Heading hierarchy, section order, and doctype-required sections
+- Requirement, risk, control, test, interface, and decision IDs
+- Numbers, units, dates, proper nouns, citations, URLs, and source mappings
+- Normative force such as Must / Should / May, approval states, and
+  acceptance criteria
+- Tables, code blocks, commands, schemas, frontmatter keys, and placeholders
+- Explicit assumptions, limitations, residual risks, and unresolved items
+
+Heading wording may improve only when its meaning and hierarchy stay intact.
+Never trade technical precision for conversational phrasing.
+
+## Optimization loop
+
+1. Inspect the host's registered skill list for `natural-japanese` or a
+   compatible Japanese prose-polishing skill. Invoke it through the host's
+   skill-loading mechanism. If the host exposes only skill files, check
+   `.github/skills/natural-japanese/SKILL.md`,
+   `.copilot/skills/natural-japanese/SKILL.md`, and
+   `$HOME/.copilot/skills/natural-japanese/SKILL.md`; expand `$HOME`, load the
+   discovered skill,
+   and follow its workflow.
+2. Ask the loaded skill to review and rewrite only the Japanese prose under
+   the frozen invariants.
+3. Let `<natural-japanese-dir>` be the directory containing the loaded
+   optimizer's `SKILL.md`. When its diagnostics are available, run the
+   optimizer's scripts with their qualified paths:
+
+   ```bash
+   uv run <natural-japanese-dir>/scripts/lint.py <target-file> --genre tech
+   uv run <natural-japanese-dir>/scripts/lint.py <target-file> --reading-load
+   uv run <natural-japanese-dir>/scripts/outline.py <target-file>
+   uv run <natural-japanese-dir>/scripts/terms.py <target-file>
+   ```
+
+   Do not substitute `skills/tech-writer/scripts/lint.py`; kotonoha's script
+   checks document structure and does not support these prose diagnostics.
+4. Triage findings in context. Do not perform blind global replacements;
+   retain a flagged expression when changing it would weaken precision or
+   alter a defined term.
+5. Re-run the optimizer's rubric and diagnostics after edits. One round is
+   one kotonoha-to-optimizer handoff and its returned edits. Allow at most
+   three rounds per §5 invocation; stop earlier when no actionable prose
+   findings remain. A later rubber-duck edit opens a new invocation limited
+   to the changed Japanese prose. Across the complete write workflow, do not
+   exceed 15 optimizer handoffs.
+6. Compare the optimized document against the frozen invariants. Revert any
+   violating edit, give the violated invariant back to the optimizer, and
+   retry within the round limit. If the violation cannot be resolved, report
+   `Japanese prose optimization did not converge`.
+7. Re-run kotonoha's doctype checklist and structural lint before
+   rubber-duck review.
+
+## Required status
+
+When this pass is in scope (a living, multi-section document whose requested
+final language is Japanese, in `write` mode), report exactly one status:
+
+- `Japanese prose optimization completed`: the registered optimizer ran and
+  no actionable prose findings remain. Run diagnostics when available; if
+  `uv` or a diagnostic script is unavailable, note that limitation without
+  changing this status.
+- `Japanese prose optimization not performed`: no compatible optimizer was
+  registered or loaded, so no prose review or rewrite ran; include the
+  concrete reason.
+- `Japanese prose optimization did not converge`: three rounds completed with
+  unresolved actionable findings or invariant violations, or the optimizer
+  started but failed before producing a valid result, a required
+  post-rubber-duck rerun failed or could not start because all 15 handoffs
+  were already used; list the findings, violations, failure, and attempted
+  fixes.
+
+Do not claim natural-language optimization based only on kotonoha's
+structural lint. Documents outside the scope of this pass require no Japanese
+optimization status.