kotonoha 0.1.6-dev.0 → 0.3.0

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

@@ -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,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.
@@ -47,25 +46,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
@@ -95,9 +94,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,15 +2,17 @@
 
 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
 
 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

@@ -6,7 +6,7 @@
 """tech-writer skill: a lint script that mechanically checks a technical
 document's *structure* and Markdown rendering safety.
 
-Where natural-japanese's lint.py detects sentence-level naturalness
+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,
@@ -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(),
                     )