kotonoha 0.1.5 → 0.2.0

package/skills/tech-writer/SKILL.md

@@ -27,10 +27,9 @@ description: >-
   question-at-a-time intake before writing. Supports both Japanese and
   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.
+  documents, it invokes kotonoha's original bundled `japanese-prose` skill,
+  which uses GiNZA for sentence-level naturalness, word choice, rhythm, and
+  repeated AI-like pattern analysis.
 license: MIT
 argument-hint: "[write|review|score] [doctype] <target file or request>"
 ---
@@ -57,13 +56,12 @@ 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). 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.
+document type conventions, completeness, reader fit). The bundled
+`japanese-prose` skill owns the second layer (sentence-level naturalness,
+reading load, terminology, and repeated-pattern analysis). Kotonoha packages
+both layers: tech-writer locks down the structure and orchestrates the §5
+handoff to japanese-prose 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?"
@@ -220,8 +218,14 @@ omissions explicitly; disclose known limitations and unsupported cases
 instead of hiding them; and keep a last-updated date or target version
 where staleness is a real risk. For Zenn/Qiita, rule 1's "first three
 lines" maps to the frontmatter `title` plus the lead paragraph right
-after it — see their doctype reference files for why there's no in-body
-'#' title.
+after it. Zenn body sections start at `##`; Qiita body sections start at
+`#` and use `##` for subsections.
+
+For every Markdown doctype, surround `**strong emphasis**` with half-width
+spaces when the delimiters would otherwise touch prose. For example, write
+`これは **強調** になる`, not `これは**強調**にならない`. Spaces are not
+required at line boundaries or next to punctuation, and must not be placed
+inside the `**` delimiters.
 
 For atomic artifacts (commit messages, PR descriptions, issue reports,
 code comments/docstrings, a single entry appended to an existing
@@ -259,30 +263,29 @@ step 2 as the primary check for those.
    (add `--atomic` for a commit message, PR description, issue report,
    code comment/docstring, or a single release-notes entry) to
    mechanically catch heading-level skips, code blocks missing a
-   language tag, leftover placeholders, and suspicious links. Findings
-   are flags, not mandates — deliberate exceptions can stay; note the reason
-   briefly.
+   language tag, leftover placeholders, suspicious links, and strong-emphasis
+   delimiters that directly touch prose. Findings are flags, not mandates —
+   deliberate exceptions can stay; note the reason briefly.
 4. **Reader-goal recheck**: confirm the "what the reader can do after
    reading" outcome from §1 is actually achievable from this document alone.
 
 ## 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.
+Japanese, read `references/japanese-prose-optimization.md` and hand the
+completed draft to kotonoha's bundled `japanese-prose` skill. This pass is
+mandatory for an in-scope document.
+
+Load `japanese-prose` through the host's skill-loading mechanism. When only
+installed skill files are exposed, resolve the sibling path
+`<tech-writer-dir>/../japanese-prose/SKILL.md` first, then check
+`.github/skills/japanese-prose/SKILL.md`,
+`.copilot/skills/japanese-prose/SKILL.md`, and
+`$HOME/.copilot/skills/japanese-prose/SKILL.md`. Load the discovered
+`SKILL.md` and follow its quick or full workflow. A standard
+`npx kotonoha install` installs this sibling skill automatically. Treat the
+pass as unavailable only when someone copied or installed tech-writer without
+its bundled sibling, or when the optimizer cannot start.
 
 Freeze heading hierarchy, section order, identifiers, numeric facts,
 citations, normative language, tables, code, commands, acceptance criteria,
@@ -388,10 +391,7 @@ of that. Common items to confirm:
 
 ## Acknowledgment
 
-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 by owning technical-document structure while orchestrating,
-but not reimplementing, the registered prose-polishing skill responsible for
-sentence-level naturalness.
+The bundled prose optimizer is an original kotonoha implementation built on
+[GiNZA](https://github.com/megagonlabs/ginza) (MIT License). Tech-writer owns
+technical-document structure while japanese-prose uses GiNZA's morphology,
+dependency, and named-entity analysis for sentence-level review.

package/skills/tech-writer/assets/templates/qiita.md

@@ -0,0 +1,44 @@
+---
+title: <記事タイトル>
+tags:
+  - <tag1>
+  - <tag2>
+private: false
+organization_url_name: null
+---
+
+<この記事が解決する具体的な課題と、読了後にできるようになることを記載する。>
+
+# 検証した環境
+
+| 項目 | バージョン・値 |
+|---|---|
+| OS | <OSとバージョン> |
+| 言語・ランタイム | <名称とバージョン> |
+| フレームワーク・ライブラリ | <名称とバージョン> |
+
+# <最初に読者へ示す結論・解決方法>
+
+<検索から到達した読者が最短で解決できるよう、結論または実行手順を先に記載する。>
+
+```bash
+<そのまま実行できる最小のコマンド例>
+```
+
+## <手順の前提または補足>
+
+<必要な権限、設定、注意点を記載する。>
+
+# <仕組み・原因・技術的な説明>
+
+<なぜこの方法で解決するのかを、図・コード・具体例を使って説明する。>
+
+# 制約と未対応事項
+
+- <確認できていない環境>
+- <適用できない条件>
+- <既知の制約>
+
+# 参考資料
+
+- [<公式ドキュメント名>](<URL>)

package/skills/tech-writer/references/doctypes/qiita.md

@@ -1,9 +1,8 @@
 # Qiita article type
 
-Like Zenn, the title lives in YAML frontmatter, not an in-body heading.
-Qiita's readership skews toward searching for a specific error message or
-task, so apply rule 3 (order matching how the reader looks for
-information) especially strictly here.
+The article title lives in YAML frontmatter. Qiita's readership skews toward
+searching for a specific error message or task, so apply rule 3 (order
+matching how the reader looks for information) especially strictly here.
 
 ## Target reader
 
@@ -13,8 +12,8 @@ is scanning to confirm this article addresses their exact situation.
 ## Format
 
 Markdown, with Qiita's frontmatter and a few platform-specific extensions
-on top of GFM. No in-body '#' heading for the article title — sections
-start at '##'.
+on top of GFM. The frontmatter `title` is the article title; body sections
+start at `#`, with `##` used for subsections.
 
 ## Recommended frontmatter
 
@@ -36,6 +35,11 @@ organization_url_name: null # only if publishing under an Organization
   automatically on publish/update — don't hand-edit those unless you know
   why.
 
+## Template
+
+Start from `assets/templates/qiita.md`.
+Use `#` for the highest-level body sections and `##` for their subsections.
+
 ## Recommended skeleton
 
 1. **Lead paragraph (right after frontmatter, before any heading)**: the
@@ -45,9 +49,10 @@ organization_url_name: null # only if publishing under an Organization
 2. **Environment / versions**: state the exact versions (language,
    framework, OS) the article was verified against, before any steps —
    Qiita readers frequently hit version-specific breakage.
-3. **Body sections, one concern per `##` heading**: order by how a reader
+3. **Body sections, one concern per `#` heading**: order by how a reader
    arriving via search would scan (rule 3) — put the fix/answer before
-   background explanation if the article is troubleshooting-oriented.
+   background explanation if the article is troubleshooting-oriented. Use
+   `##` only for subsections within one concern.
 4. **Code blocks with both a language tag and, where relevant, a filename**:
    Qiita supports ` ```js:example.js ` — prefer this over a bare language
    tag when the file identity matters to the reader.
@@ -60,6 +65,8 @@ organization_url_name: null # only if publishing under an Organization
       rather than an unconsidered default?
 - [ ] Does the lead paragraph right after frontmatter state the specific
       problem/task addressed, since there's no in-body title to do that?
+- [ ] Do highest-level body sections use `#`, with `##` reserved for
+      subsections?
 - [ ] Are the exact versions/environment stated before the steps?
 - [ ] For troubleshooting-oriented articles, does the fix appear before
       background explanation, matching how a reader arriving via search

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

@@ -5,11 +5,10 @@ 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.
+The optimizer is kotonoha's original bundled `japanese-prose` skill.
+Kotonoha owns document structure and completeness; `japanese-prose` owns
+sentence-level clarity, rhythm, word choice, reading load, terminology, and
+detection of repeated AI-like phrasing through GiNZA analysis.
 
 ## Run this pass when
 
@@ -17,8 +16,7 @@ repeated AI-like phrasing.
   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.
+- The bundled `japanese-prose` skill is readable.
 
 Skip it for English documents, generated machine-readable files, and source
 code. Also skip atomic artifacts such as commit messages, PR descriptions,
@@ -38,6 +36,8 @@ outcome. Require it to preserve:
 - Normative force such as Must / Should / May, approval states, and
   acceptance criteria
 - Tables, code blocks, commands, schemas, frontmatter keys, and placeholders
+- Markdown emphasis spacing: keep half-width spaces between surrounding prose
+  and `**strong emphasis**` delimiters
 - Explicit assumptions, limitations, residual risks, and unresolved items
 
 Heading wording may improve only when its meaning and hierarchy stay intact.
@@ -45,25 +45,25 @@ 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
+1. Invoke kotonoha's bundled `japanese-prose` through the host's
+   skill-loading mechanism. If the host exposes only skill files, resolve
+   `<tech-writer-dir>/../japanese-prose/SKILL.md` first, then check
+   `.github/skills/japanese-prose/SKILL.md`,
+   `.copilot/skills/japanese-prose/SKILL.md`, and
+   `$HOME/.copilot/skills/japanese-prose/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
+3. Let `<japanese-prose-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>
+   uv run <japanese-prose-dir>/scripts/lint.py <target-file> --genre tech --json > <workdir>/prose-baseline.json
+   uv run <japanese-prose-dir>/scripts/lint.py <target-file> --genre tech --reading-load
+   uv run <japanese-prose-dir>/scripts/outline.py <target-file>
+   uv run <japanese-prose-dir>/scripts/terms.py <target-file>
    ```
 
    Do not substitute `skills/tech-writer/scripts/lint.py`; kotonoha's script
@@ -93,9 +93,10 @@ final language is Japanese, in `write` mode), report exactly one status:
   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 not performed`: the bundled optimizer was
+  missing or unreadable, so no prose review or rewrite ran; include the
+  concrete reason. A standard `npx kotonoha install` should prevent this
+  state.
 - `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

package/skills/tech-writer/references/style-constitution.md

@@ -2,7 +2,7 @@
 
 Constraints to fix a technical document's *structure* before writing.
 Sentence-level naturalness, vocabulary, and rhythm are out of scope here
-(→ the domain of a prose-polishing skill such as natural-japanese).
+(→ the domain of kotonoha's bundled `japanese-prose` skill).
 
 ## Scope: living documents vs. atomic artifacts
 
@@ -10,11 +10,11 @@ These 8 rules assume a **living, multi-section reference document** —
 README, design doc/ADR, API reference, release notes/CHANGELOG file as a
 whole, user manual, technical proposal, RFI/RFP (including a supplier's RFP
 response), or Zenn/Qiita article. Apply all 8 rules to those doctypes. For
-Zenn/Qiita specifically, rule 1's "title" lives in YAML frontmatter rather
-than an in-body '#' heading — see their doctype reference files for the
-platform-specific frontmatter fields — but every other rule (heading
-hierarchy starting at '##', code examples, disclosed limitations, etc.)
-still applies verbatim.
+Zenn and Qiita, rule 1's article title lives in YAML frontmatter — see their
+doctype reference files for the platform-specific fields. Zenn body sections
+start at `##`; Qiita body sections start at `#` and use `##` for subsections.
+Every other rule (code examples, disclosed limitations, etc.) still applies
+verbatim.
 
 **Atomic, single-purpose artifacts** — commit messages, PR descriptions,
 issue reports, code comments/docstrings, and a single new entry appended
@@ -28,6 +28,14 @@ a title-plus-paragraph). Follow that doctype's own skeleton for those
 instead of applying the heading-hierarchy and document-metadata rules
 below verbatim; where the two disagree, the doctype reference wins.
 
+## Markdown emphasis spacing
+
+In generated Markdown, add half-width spaces outside strong-emphasis
+delimiters when they touch surrounding prose. Write
+`これは **強調** になる` rather than `これは**強調**にならない`.
+The spaces are unnecessary at a line boundary or next to punctuation, for
+example `**重要**: 設定を確認する`. Never put spaces inside the delimiters.
+
 ## 1. Say "what this is" and "the outcome" in the first three lines
 
 Readers decide "is this relevant to me" within the first three lines. Don't

package/skills/tech-writer/scripts/lint.py

@@ -4,12 +4,13 @@
 # dependencies = []
 # ///
 """tech-writer skill: a lint script that mechanically checks a technical
-document's *structure*.
+document's *structure* and Markdown rendering safety.
 
-Where natural-japanese's lint.py detects sentence-level naturalness
-(vocabulary, rhythm), this script only detects structural problems specific
-to technical documents (heading hierarchy, code examples, leftover
-placeholders, suspicious links). The two scripts intentionally don't
+Where japanese-prose's GiNZA lint detects sentence-level naturalness
+(vocabulary, rhythm), this script detects structural problems specific to
+technical documents plus Markdown syntax patterns that render inconsistently
+(heading hierarchy, code examples, leftover placeholders, suspicious links,
+and bold delimiters touching prose). The two scripts intentionally don't
 overlap in scope.
 
 Findings are flags, not mandates: exit code is always 0 regardless of the
@@ -73,6 +74,7 @@ FENCE_RE = re.compile(r"^(`{3,}|~{3,})(.*)$")
 PLACEHOLDER_RE = re.compile(r"\b(TODO|FIXME|TBD|XXX)\b", re.IGNORECASE)
 MD_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
 INLINE_CODE_RE = re.compile(r"`[^`\n]+`")
+BOLD_RE = re.compile(r"(?<![\\*])\*\*(?!\s)(.+?)(?<!\s)\*\*(?!\*)")
 NON_PARAGRAPH_RE = re.compile(
     r"^(?:[-*+]\s|\d+[.)]\s|>|<!--|\|)|^(?:-{3,}|\*{3,}|_{3,})$"
 )
@@ -243,6 +245,39 @@ def check_links(lines: list, fence_mask: list) -> list:
     return findings
 
 
+def check_bold_spacing(lines: list, fence_mask: list) -> list:
+    """Flag bold delimiters that directly touch surrounding prose.
+
+    Some Markdown renderers fail to recognize strong emphasis when `**`
+    directly adjoins Japanese or other word characters. Punctuation and
+    line boundaries do not need padding.
+    """
+    findings = []
+    for i, line in enumerate(lines):
+        if fence_mask[i]:
+            continue
+        checked = strip_inline_code(line)
+        for match in BOLD_RE.finditer(checked):
+            before = checked[match.start() - 1] if match.start() else ""
+            after = checked[match.end()] if match.end() < len(checked) else ""
+            if (before and (before.isalnum() or before == "_")) or (
+                after and (after.isalnum() or after == "_")
+            ):
+                findings.append(
+                    Finding(
+                        line=i + 1,
+                        category="bold_spacing",
+                        message=(
+                            "Add half-width spaces outside '**...**' when it "
+                            "touches surrounding prose so strong emphasis "
+                            "renders consistently."
+                        ),
+                        snippet=line.strip(),
+                    )
+                )
+    return findings
+
+
 def check_intro_paragraph(lines: list, fence_mask: list) -> list:
     """Check that the document opens with a non-empty H1 title immediately
     followed by a genuine body paragraph.
@@ -315,6 +350,7 @@ def run_lint(path: Path, atomic: bool = False) -> LintResult:
     result.findings.extend(check_heading_hierarchy(lines, fence_mask))
     result.findings.extend(check_placeholders(lines, fence_mask))
     result.findings.extend(check_links(lines, fence_mask))
+    result.findings.extend(check_bold_spacing(lines, fence_mask))
     if not atomic:
         # check_intro_paragraph assumes a living, multi-section document
         # (H1 title + opening paragraph); atomic artifacts like a PR