kotonoha 0.2.0 → 0.4.0

package/skills/tech-writer/assets/templates/white-paper.md

@@ -0,0 +1,192 @@
+# <White Paperタイトル>
+
+<対象読者が抱える問題、本書の中心的な結論、読後に判断できることを3文以内で記載する。>
+
+- 発行者: <組織名>
+- 著者・監修者: <氏名・役割>
+- 発行日: <YYYY-MM-DD>
+- 最終更新日: <YYYY-MM-DD>
+- 版: <版番号>
+- ステータス: Draft / In Review / Approved for Publication / Withdrawn
+- 公開承認者: <氏名・役割・会議体>
+- 法務・コンプライアンス・主張レビュー: <レビュー者・該当なし>
+- 対象読者: <読者>
+- 対象地域・業界: <範囲>
+- 調査対象期間: <YYYY-MM-DD〜YYYY-MM-DD>
+- 公開区分: Public / Limited / Confidential
+- Analysis status: Completed / Incomplete / Not performed
+- Evidence gaps: <不足する証拠、影響する判断、収集担当・期限、またはなし>
+- 分析ハンドオフ: <synthesis-handoff.mdの所在、またはなし>
+
+`Analysis status`は公開承認ステータスとは別に記録する。`Incomplete`の場合は、不足する証拠と確からしさを明示し、影響する結論・推奨事項を条件付きで記載する。判断を妨げる不足は`consulting-analyst`へ戻すか、この文書に残す。`Not performed`の場合は、分析未実施の範囲と理由を記載し、分析済みとして扱わない。
+
+## 要旨
+
+<問題、調査・分析の範囲、主要な発見、結論、読者への示唆を300〜500字で記載する。本文を読まなくても中心的な判断が分かるようにする。>
+
+## 本書が答える問い
+
+- 中心的な問い: <読者が判断したい問い>
+- 中心的な主張: <証拠で支持または反証できる具体的な主張>
+- 読者に求める次の行動: <検討、評価、実証、導入判断など>
+
+## 対象範囲と用語
+
+### 対象範囲
+
+- 含む: <地域、業界、組織規模、技術、期間>
+- 含まない: <対象外と、その理由>
+- 情報の基準日: <YYYY-MM-DD>
+
+### 主要用語
+
+| 用語 | 本書での定義 | 類似語との違い |
+|---|---|---|
+| <用語> | <定義> | <違い> |
+
+## 調査・分析方法
+
+<どの情報を、どの基準で収集・評価・統合したかを記載する。>
+
+| 方法 | 対象・件数 | 選定基準 | 分析方法 | 主な制約 |
+|---|---:|---|---|---|
+| 文献調査 / インタビュー / データ分析 / 実証 | <対象> | <基準> | <方法> | <制約> |
+
+### 証拠の評価基準
+
+- 一次情報を優先する条件: <条件>
+- 情報の新しさを判断する基準: <基準>
+- 利害関係のある情報の扱い: <検証・注記方法>
+- 不一致または反証となる情報の扱い: <方法>
+
+## <問題が重要になる背景>
+
+<市場、制度、利用者、技術、運用などの変化を、出典付きの事実と分析者の解釈に分けて説明する。>
+
+## 調査から得られた主要な発見
+
+### <発見1を結論として表す見出し>
+
+<発見を最初に記載し、その後に証拠、解釈、適用範囲を説明する。>
+
+| 項目 | 内容 |
+|---|---|
+| 主張ID | CLM-001 |
+| 主張 | <具体的な主張> |
+| 関連仮説 HYP IDs | <関連HYP IDs、または理由付きN/A> |
+| 分析上の発見 FND IDs | <関連FND IDs、または理由付きN/A> |
+| 根拠 | EVD-001、EVD-002 |
+| 確からしさ | High / Medium / Low |
+| 適用範囲 | <どこまで当てはまるか> |
+| 制約・反証 | <弱める条件、矛盾する証拠> |
+
+### <発見2を結論として表す見出し>
+
+<必要な数だけ同じ構造で記載する。>
+
+## 選択肢と評価
+
+| 選択肢 | 適する状況 | 期待効果 | 費用・負担 | リスク | 根拠 |
+|---|---|---|---|---|---|
+| 現状維持 | <状況> | <効果> | <負担> | <リスク> | <証拠ID> |
+| <選択肢> | <状況> | <効果> | <負担> | <リスク> | <証拠ID> |
+
+## 推奨する考え方またはソリューションパターン
+
+<推奨事項を、適用条件とともに記載する。製品やサービスを例示する場合は、一般的な結論と製品固有の主張を分ける。>
+
+```mermaid
+flowchart LR
+    A[<課題・入力>] --> B[<推奨する能力・方式>]
+    B --> C[<期待する成果>]
+```
+
+### 適用条件
+
+- 適する条件: <条件>
+- 適さない条件: <条件>
+- 事前に検証する事項: <PoC・評価・法務確認など>
+
+## 導入・適用時に検討する事項
+
+| 観点 | 確認事項 | 判断材料 | 主なリスク |
+|---|---|---|---|
+| 組織・人材 | <確認事項> | <証拠・測定> | <リスク> |
+| 業務・ガバナンス | <確認事項> | <証拠・測定> | <リスク> |
+| データ・技術 | <確認事項> | <証拠・測定> | <リスク> |
+| セキュリティ・法令 | <確認事項> | <証拠・測定> | <リスク> |
+| 費用・運用 | <確認事項> | <証拠・測定> | <リスク> |
+
+## 事例または検証結果
+
+<事例、実証、シミュレーションのどれかを明示する。代表性を保証しない場合は、その制約を記載する。>
+
+| 項目 | 内容 |
+|---|---|
+| 対象 | <組織・環境・条件> |
+| 実施内容 | <方法> |
+| 結果 | <測定値> |
+| 比較基準 | <導入前・対照・目標> |
+| 制約 | <一般化できない理由> |
+| 出典 | <証拠ID・URL> |
+| 顧客名・数値・事例の掲載許諾 | <許諾者・許諾日・条件、または匿名化の方法> |
+
+## 反対意見・代替解釈・限界
+
+- 反対意見: <有力な異論と、その根拠>
+- 代替解釈: <同じ証拠から導ける別の結論>
+- データの限界: <欠損、偏り、サンプル、期間>
+- 将来変化する可能性: <技術、制度、市場など>
+- 結論を見直す条件: <新しい証拠・閾値>
+
+## 結論と次の判断
+
+<中心的な問いへの回答を簡潔に示し、対象読者が次に行う評価・合意・実証・意思決定を記載する。新しい主張は追加しない。>
+
+## 利害関係と開示
+
+- 発行者と対象製品・サービスの関係: <関係・該当なし>
+- 資金提供・協賛: <提供者・該当なし>
+- 著者の利害関係: <内容・該当なし>
+- データ提供者の関与: <収集、分析、レビューへの関与>
+- AI利用: <調査・執筆・翻訳・校正での利用範囲>
+
+## 証拠台帳
+
+SRCは出典の記録、EVDは分析上の証拠の記録を表す。分析ハンドオフがある場合は、関連するHYP / FND / EVD IDsを主張・発見に紐付け、元のIDと意味を保持する。出典をEVDに置き換えない。該当しないリンクは理由付き`N/A`とし、ハンドオフがない場合はHYP / FND IDsを無理に作らない。
+
+### 出典の記録
+
+| 出典ID | 出典 | 種別 | 発行日 | 参照日 | 関連する証拠ID | 品質・制約 |
+|---|---|---|---|---|---|---|
+| SRC-001 | <著者、資料名、URL> | 一次 / 二次 | <YYYY-MM-DD> | <YYYY-MM-DD> | EVD-001 | <評価> |
+
+### 分析上の証拠の記録
+
+| 証拠ID | 出典ID | 記述の種別 | 証拠または解釈 | 関連仮説 HYP IDs | 関連発見 FND IDs | 関連主張 | 品質・制約 |
+|---|---|---|---|---|---|---|---|
+| EVD-001 | SRC-001 | Fact / Estimate / Interpretation | <証拠、または解釈とその根拠EVD IDs> | <関連HYP IDs、またはN/A> | <関連FND IDs、またはN/A> | CLM-001 | <評価> |
+
+Interpretationは解釈として保持し、仮説を支持する証拠には数えない。`Supported`の仮説には、その仮説を支持するFact / EstimateのEVDが必要となる。
+
+## 参考文献
+
+1. <著者・組織>『<資料名>』<発行年>、<URL>（参照日: <YYYY-MM-DD>）
+
+## 公開承認とレビュー記録
+
+ステータスを`Approved for Publication`にするには、公開承認と、必須レビューの`Approved`または理由付き`N/A`が揃っていることを確認する。`Withdrawn`の場合は、撤回日と理由を記録する。
+
+| 種別 | レビュー者・承認者 | 対象 | 判断 | 日付 | 条件・N/Aの理由 |
+|---|---|---|---|---|---|
+| 公開承認 | <氏名・役割・会議体> | 文書全体 | Approved / Rejected | <YYYY-MM-DD> | <条件> |
+| 法務レビュー | <氏名・役割> | <対象箇所・文書全体> | Approved / Rejected / N/A | <YYYY-MM-DD> | <条件・N/Aの理由> |
+| コンプライアンスレビュー | <氏名・役割> | <対象箇所・文書全体> | Approved / Rejected / N/A | <YYYY-MM-DD> | <条件・N/Aの理由> |
+| 主張・数値検証 | <氏名・役割> | <CLM・EVD・事例ID> | Approved / Rejected / N/A | <YYYY-MM-DD> | <条件・N/Aの理由> |
+| 顧客名・事例掲載許諾 | <許諾者・確認者> | <事例・顧客名・数値> | Approved / Rejected / N/A | <YYYY-MM-DD> | <条件・匿名化・N/Aの理由> |
+
+## 変更履歴
+
+| 版 | 日付 | 変更内容 | 変更者 | レビュー者 |
+|---|---|---|---|---|
+| 0.1 | <YYYY-MM-DD> | 初版 | <氏名> | <氏名> |

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

@@ -0,0 +1,81 @@
+# Blueprint type
+
+A Blueprint defines an agreed future state and the coordinated path from the
+current state to that future state. It can cover technology, business
+capabilities, operating models, governance, or a combination of them. It is
+broader and more directional than a system design, but more executable than a
+vision statement or strategy narrative.
+
+## Target reader
+
+Sponsors, architects, transformation leads, delivery owners, governance
+bodies, and affected teams who must align on the destination, sequence,
+decision rights, dependencies, and measures of progress.
+
+## Settle before writing
+
+- The outcome and planning horizon covered by the Blueprint
+- The current-state baseline and evidence supporting it
+- The target capabilities and principles that constrain the future state
+- The dimensions in scope: business, organization, process, data, technology,
+  security, governance, or operations
+- The authority that approves the Blueprint and owns subsequent changes
+- The level of detail needed for funding, portfolio planning, or delivery
+
+## Responsibility boundary
+
+A Blueprint establishes direction, boundaries, target capabilities, major
+building blocks, transformation workstreams, and sequencing. It does not
+replace implementation-level system designs, detailed requirements, project
+plans, operating procedures, or an investment approval proposal.
+
+Use `system-design` when teams need buildable component, interface, data, and
+deployment details. Use `technical-proposal` when the primary outcome is an
+approval of one investment or approach. Use `blueprint` when multiple
+initiatives or organizational and technical dimensions must converge on one
+future state over time.
+
+## Template
+
+Start from `assets/templates/blueprint.md`.
+The template is the Japanese-language skeleton; translate its headings when
+the target document is English.
+
+## Recommended skeleton
+
+1. Intended outcome, planning horizon, scope, and authority
+2. Drivers, principles, current-state baseline, and constraints
+3. Target capabilities and future-state operating and technical views
+4. Gap analysis, workstreams, dependencies, and transition states
+5. Phased roadmap with entry, exit, and decision criteria
+6. Governance, measures, risks, traceability, and change control
+
+## Checklist
+
+- [ ] Is the planning horizon and approval authority explicit?
+- [ ] Is `Analysis status: Completed / Incomplete / Not performed` recorded
+      separately from approval status, with `Evidence gaps` and the analysis
+      handoff location (or none)?
+- [ ] For `Incomplete`, are evidence gaps and confidence visible and every
+      affected conclusion or recommendation expressed with conditional wording,
+      or returned to consulting-analyst? For `Not performed`, are the scope and
+      reason explicit without implying completed analysis?
+- [ ] Is the current state supported by evidence rather than assumption?
+- [ ] Are target capabilities stated before products or implementation detail?
+- [ ] Are business, process, data, technology, security, governance, and
+      operations dimensions included or explicitly marked out of scope?
+- [ ] Does each gap map to a workstream, owner, dependency, and target state?
+- [ ] Do roadmap phases have entry conditions, exit conditions, and measurable
+      outcomes rather than dates alone?
+- [ ] Are transition states, coexistence, migration, and decommissioning
+      concerns visible?
+- [ ] Are decision rights, exception handling, and change control defined?
+- [ ] Can strategic drivers be traced through capabilities and workstreams to
+      measures?
+- [ ] Does traceability preserve relevant Q / HYP / FND / EVD and GAP / INT / CRT
+      IDs from the consulting handoff alongside driver, principle, capability,
+      gap, workstream, and KPI IDs? Are inapplicable links marked `N/A` with a
+      reason without forcing consulting IDs when no consulting handoff exists?
+- [ ] Are assumptions, risks, unresolved decisions, and superseded versions
+      recorded?
+- [ ] Does the header status match the approval outcome?

package/skills/tech-writer/references/doctypes/white-paper.md

@@ -0,0 +1,84 @@
+# White Paper type
+
+A White Paper helps a defined audience understand a consequential problem,
+evaluate evidence, and reach an informed conclusion. It may explain an
+emerging topic, establish a point of view, or describe a solution pattern,
+but it must distinguish evidence from interpretation and must not disguise
+marketing claims as independent analysis.
+
+## Target reader
+
+Decision-makers, practitioners, evaluators, customers, partners, regulators,
+or industry readers who need a credible explanation and a defensible basis
+for action.
+
+## Settle before writing
+
+- The reader's decision, question, or misconception the paper addresses
+- The central claim and what evidence could weaken or disprove it
+- The publication scope, date boundary, geography, and intended longevity
+- The research method and acceptable source quality
+- The publisher's relationship to products, services, sponsors, or cited data
+- The desired next action, without overstating certainty
+
+## Responsibility boundary
+
+A White Paper explains and supports a position. It is not a requirements
+specification, implementation design, sales brochure, academic paper, or
+contractual promise. Product examples may illustrate a finding, but factual
+claims, estimates, customer outcomes, and recommendations must remain
+traceable to named evidence and limitations.
+
+Use `technical-proposal` for an internal approval request, `blueprint` for a
+future state and transformation roadmap, and `white-paper` for an
+evidence-led public or stakeholder-facing argument.
+
+## Template
+
+Start from `assets/templates/white-paper.md`.
+The template is the Japanese-language skeleton; translate its headings when
+the target document is English.
+
+## Recommended skeleton
+
+1. Title, abstract, target reader, central claim, and disclosure
+2. Problem definition, scope, terminology, and research method
+3. Evidence-led findings with confidence and limitations
+4. Options, solution pattern, recommendation, and adoption considerations
+5. Counterarguments, risks, boundaries, and conclusion
+6. References, evidence ledger, glossary, authorship, and revision history
+
+## Checklist
+
+- [ ] Does the abstract state the problem, conclusion, audience, and practical
+      consequence?
+- [ ] Is `Analysis status: Completed / Incomplete / Not performed` recorded
+      separately from publication status, with `Evidence gaps` and the analysis
+      handoff location (or none)?
+- [ ] For `Incomplete`, are evidence gaps and confidence visible and every
+      affected conclusion or recommendation expressed with conditional wording,
+      or returned to consulting-analyst? For `Not performed`, are the scope and
+      reason explicit without implying completed analysis?
+- [ ] Is the central claim specific enough to challenge with evidence?
+- [ ] Are facts, estimates, interpretations, and recommendations visibly
+      distinguished?
+- [ ] Does every consequential claim link to a source or evidence identifier?
+- [ ] Does the evidence ledger keep SRC source records separate from EVD analysis
+      evidence, preserving their IDs and meaning?
+- [ ] Do claims and findings link relevant HYP / FND / EVD IDs from the handoff,
+      marking inapplicable links `N/A` with a reason without forcing consulting
+      IDs when no consulting handoff exists?
+- [ ] Are interpretations preserved without counting as supporting evidence,
+      with `Supported` hypotheses backed by relevant Fact / Estimate evidence?
+- [ ] Are source date, scope, method, sample, and limitations available?
+- [ ] Are contradictory evidence and credible alternatives addressed?
+- [ ] Are product, sponsor, author, and data-source relationships disclosed?
+- [ ] Are publication approval and legal, compliance, and claims reviews
+      recorded, including approval to use customer names and quantitative
+      claims?
+- [ ] Does `Approved for Publication` match a complete approval record, with
+      a reason recorded for every review marked not applicable?
+- [ ] Are case studies labeled and prevented from implying universal results?
+- [ ] Does the recommendation state where it does not apply?
+- [ ] Can readers reproduce the source trail and identify the document's
+      publication and revision dates?

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

@@ -36,8 +36,9 @@ 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
+- Markdown emphasis spacing: keep ASCII half-width spaces (`U+0020`) between
+  surrounding prose and both sides of `**strong emphasis**` delimiters; never
+  substitute full-width spaces (`U+3000`), tabs, or non-breaking spaces
 - Explicit assumptions, limitations, residual risks, and unresolved items
 
 Heading wording may improve only when its meaning and hierarchy stay intact.
@@ -54,7 +55,9 @@ Never trade technical precision for conversational phrasing.
    discovered skill,
    and follow its workflow.
 2. Ask the loaded skill to review and rewrite only the Japanese prose under
-   the frozen invariants.
+   the frozen invariants. Save an immutable pre-edit copy, pass the frozen
+   proper names and domain terms for `--protect`, and keep necessary
+   corrections separate from optional wording changes.
 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:
@@ -81,6 +84,12 @@ Never trade technical precision for conversational phrasing.
    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`.
+   Run `<japanese-prose-dir>/scripts/invariants.py` against the immutable
+   original and current target. Require a hash-bound contextual semantic
+   review for changed prose, following the optimizer's review workflow.
+   A `review_required` result or an unavailable/failed invariant gate cannot
+   be treated as completion. Rerun after rubber-duck edits; old review hashes
+   do not approve new text.
 7. Re-run kotonoha's doctype checklist and structural lint before
    rubber-duck review.
 
@@ -90,9 +99,9 @@ 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.
+  no actionable prose findings remain, and the invariant gate passed with
+  a current semantic review of any edits. A missing optional diagnostic may
+  be noted, but a missing or failed invariant gate prevents this status.
 - `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
@@ -101,8 +110,8 @@ final language is Japanese, in `write` mode), report exactly one status:
   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.
+  were already used, or the invariant gate/semantic review could not pass;
+  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

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

@@ -8,9 +8,11 @@ Sentence-level naturalness, vocabulary, and rhythm are out of scope here
 
 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 and Qiita, rule 1's article title lives in YAML frontmatter — see their
+whole, user manual, requirements definition, system design, test plan,
+operations runbook, migration plan, security design, technical proposal,
+Blueprint, White Paper, RFI/RFP (including a supplier's RFP response), or
+Zenn/Qiita article. Apply all 8 rules to those doctypes. For 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
@@ -34,7 +36,11 @@ 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.
+example `**重要**: 設定を確認する`. Use ASCII spaces (`U+0020`), not
+full-width spaces (`U+3000`), tabs, or non-breaking spaces, immediately before
+and after emphasis embedded in prose. Write `これは **「重要」** と説明する`,
+not `これは　**「重要」**　と説明する`. Never put spaces inside the
+delimiters.
 
 ## 1. Say "what this is" and "the outcome" in the first three lines
 

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

@@ -246,11 +246,12 @@ def check_links(lines: list, fence_mask: list) -> list:
 
 
 def check_bold_spacing(lines: list, fence_mask: list) -> list:
-    """Flag bold delimiters that directly touch surrounding prose.
+    """Flag bold delimiters with missing or non-ASCII surrounding spaces.
 
     Some Markdown renderers fail to recognize strong emphasis when `**`
     directly adjoins Japanese or other word characters. Punctuation and
-    line boundaries do not need padding.
+    line boundaries do not need padding. When padding is present, it must
+    be an ASCII half-width space rather than a tab or Unicode space.
     """
     findings = []
     for i, line in enumerate(lines):
@@ -262,15 +263,19 @@ def check_bold_spacing(lines: list, fence_mask: list) -> list:
             after = checked[match.end()] if match.end() < len(checked) else ""
             if (before and (before.isalnum() or before == "_")) or (
                 after and (after.isalnum() or after == "_")
+            ) or (
+                before and before.isspace() and before != " "
+            ) or (
+                after and after.isspace() and 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."
+                            "Use ASCII half-width spaces immediately before "
+                            "and after '**...**' when it is embedded in prose; "
+                            "do not use full-width or other Unicode spaces."
                         ),
                         snippet=line.strip(),
                     )