@litfamily/litopencode 1.0.16 → 1.0.17

package/skills/lit-docx/references/tonalities/manual.md

@@ -0,0 +1,111 @@
+# Manual
+
+Pack: `templates/tonalities/manual.yaml` · dials density 9, variance 6 · accent #2E4A66 on the callout
+rules and the sidebar rule.
+
+## Purpose
+
+A Manual is used, not read through: an operating procedure, a maintenance guide, an onboarding guide, a
+safety procedure, a work instruction. The reader has a task in front of them and looks for the section
+that covers it, follows numbered steps, stops at warnings and checks values in reference tables. Korean
+절차서, 운영 지침, 작업 표준 and 매뉴얼 belong here.
+
+## Wrong for
+
+- A document reporting what happened rather than what to do: use a Report.
+- A one-page instruction with three steps: use a Memo, with the steps as a numbered list.
+- A policy or decision paper: use a Brief.
+
+## Structure
+
+| Feature | What the pack sets |
+|---|---|
+| Page 1 | title and subtitle over a document-control block between two hairlines: document (`short_title` or `title`), owner (`author`), organisation (`organization`), issued (`date`); the notice under it |
+| Summary | prose; most manuals open with scope and responsibilities instead of a summary |
+| Numbering | 1 / 1.1 / 1.1.1, so steps and sections can be cited ("see 3.2") |
+| Components | callout (one style for every warning), sidebar, columns |
+| Running head | header: short title; footer: folio right; none on page 1 |
+| Contents | a short list of h1 headings with page numbers, when the source is long enough for about five pages |
+
+The control block labels are 문서 / 작성 부서 / 기관 / 시행일 in Korean and Document / Owner /
+Organisation / Issued in English. The block counts as a component kind for the gate's
+`component.variety` check.
+
+## Type scale
+
+Body 10.5 pt, h1 14 pt, h2 12 pt, h3 10.5 pt bold, title 26.5 pt, table text 9.5 pt; sidebar text at table
+size. Ragged right in both languages, which keeps step text from stretching. Decimal heading numbers sit
+in a hanging indent wide enough for the widest number, so the heading texts of a level start on one line.
+
+## Components
+
+- **Callout, `kind=warning`.** A hazard, an irreversible step, a forbidden combination. Place it directly
+  before the step it protects, not at the end of the section. All warnings share one style; there is no
+  separate danger or caution colour. The budget is about one box per four pages, so a short manual gets
+  one; the converter keeps warnings ahead of notes when it chooses. Write the most serious one as the box
+  and fold the others into the step text.
+- **Sidebar.** Definitions, contact numbers or reference values the reader looks up while following the
+  text. Floats right at a third of the width by default. Needs two or three paragraphs after it before
+  the next heading, or it stands full width.
+- **Columns.** Two balanced blocks, such as the same check on two machine types.
+
+## Writing the source
+
+- Do not use a `::: cover` directive unless you want a kicker line above the title; the control block
+  comes from the frontmatter.
+- Open with scope and responsibilities: what the manual covers, what it does not, who does what.
+- Write each procedure as a Markdown numbered list (`1.`, `2.`, …), one action per step, in the
+  imperative. Each new list restarts at 1.
+- Put conditions and values in tables (inspection items with their limits and the action when a limit is
+  missed).
+- Keep warnings short: what not to do, what happens if you do, what to do instead.
+- End with the emergency or exception procedure, also as numbered steps.
+
+## Source fragment
+
+```markdown
+---
+title: Walk-in freezer daily check procedure
+subtitle: Opening checks, temperature logging and alarm response for kitchen staff
+author: Facilities Team
+organization: Example catering site
+date: 2026-11-20
+short_title: Freezer daily checks
+notice: Sample procedure. Equipment, limits and contacts are invented examples.
+tonality: Manual
+---
+
+# Opening checks
+
+Complete these checks before the first delivery is put away. They take about five minutes.
+
+1. Read the display temperature and write it in the log with the time.
+2. Check that the door closes fully and the seal shows no ice build-up.
+3. Check the floor for water near the evaporator drain.
+
+::: callout kind=warning title="Door left open"
+Do not prop the door open during deliveries. The evaporator ices over within twenty minutes and the
+freezer may take two hours to recover. Close the door between trolley loads.
+:::
+
+## Temperature limits
+
+Table 1. Freezer temperature limits
+
+| Reading | Status | Action |
+|---|---|---|
+| -18 °C or colder | Normal | Log and continue |
+| -17 to -15 °C | Warning | Recheck in 30 minutes |
+| Warmer than -15 °C | Alarm | Follow section 3 |
+```
+
+The h1 prints as `1 Opening checks` and the h2 as `1.1 Temperature limits`; the control block on page 1
+lists Freezer daily checks, Facilities Team, Example catering site and 20 November 2026.
+
+## Before delivery
+
+- Every step is one action and starts with a verb.
+- Every warning stands before the step it protects.
+- Cross-references use the printed section numbers, which the converter assigns in order; check them
+  after any section is added or removed.
+- Reference tables give a value, a status and an action in every row.

package/skills/lit-docx/references/tonalities/memo.md

@@ -0,0 +1,105 @@
+# Memo
+
+Pack: `templates/tonalities/memo.yaml` · dials density 9, variance 2 · no accent.
+
+## Purpose
+
+A Memo tells a group of people something they need to know or do, in one or two pages: a notice of works
+or a schedule change, an internal memo, a request for cooperation, a short letter, a decision already
+taken and now announced. Korean 안내문, 공지, 협조 요청 and 업무 연락 fit here. The reader wants the
+subject, what changes, what they must do and whom to ask, and stops reading there.
+
+## Wrong for
+
+- A request that someone approve something: use a Brief, which puts the decision box first.
+- More than two pages, or more than two tables: use a Report or a Manual.
+- A procedure with warnings: use a Manual.
+
+## Structure
+
+| Feature | What the pack sets |
+|---|---|
+| Page 1 | no cover and no masthead: a small label (the kicker, default 메모 / Memo), the subject as the title at 1.8 times the body size, then rows of To / From / Date / Subject between two hairlines, then the notice |
+| Summary | none; the first section says what happens |
+| Numbering | none |
+| Components | none; a callout or other directive is set as its bold title and plain text |
+| Running head | footer: folio right, from page 2 |
+| Contents | never |
+
+The rows come from the lines of the `::: cover` body that start with `To:`, `From:`, `Date:`, `Subject:`,
+`Cc:` or the Korean `받는 사람:`, `보내는 사람:`, `날짜:`, `제목:`, `참조:`. Several pairs may share a line
+when separated by ` · `. When no date row is written, the frontmatter date is inserted after the sender,
+formatted for the language (2026. 10. 12. or 12 October 2026). English values are capitalised. The block
+counts as a component kind for the gate.
+
+## Type scale
+
+Korean body 10.5 pt, h1 12.5 pt, h2 11.5 pt, title 19 pt. English body 11 pt, h1 13 pt, h2 12 pt, title
+20 pt. The smallest heading steps of any pack: in a memo the headings are signposts, not chapters.
+Korean justified.
+
+The pack sets `spacing: tight`, so a memo whose content allows stays on one page: line pitch at the low
+end (Hangul 165 %, Latin 120 %), heading space of 12/5, 10/4, 9/3 and 8/3 pt before and after, table cells
+2 pt top and bottom. A run-in head (a callout's bold title) keeps 12 pt above it, so it starts a block, and
+a paragraph after a list stands 6 pt clear of the list's last item.
+
+## Components
+
+None. The memo's single structural device is its header block. A point that seems to need a box is
+better written as the first sentence of its section. If the source holds a callout anyway, the converter
+prints its title as a bold line and the body as plain paragraphs.
+
+## Writing the source
+
+- Put the To / From lines in the cover directive and give it a kicker that names the kind of memo (안내,
+  공지, 협조 요청, Notice, Request).
+- The title is the subject line: what, where, when ("본관 승강기 교체 공사 기간 이용 안내", "Car park
+  closure, 3 to 7 November").
+- Three to five short sections: what changes, what readers should do, any exceptions, whom to contact.
+- One small table at most, for a schedule or a before-and-after comparison, with a caption.
+- Polite address (합니다체) is normal in a Korean notice addressed to staff; keep it consistent through the
+  memo.
+- Give a named contact with an extension or address in the last section.
+
+## Source fragment
+
+```markdown
+---
+title: Car park closure for resurfacing, 3 to 7 November
+author: Estates Office
+organization: Example college
+date: 2026-10-21
+notice: Sample memo. Names, dates and locations are invented examples.
+tonality: Memo
+---
+
+::: cover kicker="Notice"
+To: All staff and students · From: Estates Office · Cc: Security desk
+:::
+
+# Closed area and dates
+
+The main car park on Mill Lane will be closed from 07:00 on Monday 3 November until 18:00 on Friday
+7 November while the surface is replaced. Blue-badge bays by the library entrance stay open.
+
+# Where to park instead
+
+Staff permits are valid at the Riverside overflow car park for the week. A shuttle minibus runs from
+Riverside to the main entrance every fifteen minutes between 07:30 and 09:30 and between 16:00 and 18:30.
+
+# Questions
+
+Contact the Estates Office on extension 2210 or at estates@example.org.
+```
+
+The header block reads To, From, Date (21 October 2026, inserted after From) and Cc, with "Notice" above
+the title.
+
+## Before delivery
+
+- The rendered memo is two pages or fewer; page 1 carries no folio. A memo that runs onto a second page
+  and fills less than a quarter of it fails `memo.fit` (`qa --layout`): tighten the prose by the lines
+  that spill; a memo that needs a real second page keeps it.
+- The subject, the date of the change and the action required are on page 1.
+- No component box appears; the qa output shows only the memo block.
+- Contact details are real for the organisation or clearly marked as examples by the notice.

package/skills/lit-docx/references/tonalities/proposal.md

@@ -0,0 +1,101 @@
+# Proposal
+
+Pack: `templates/tonalities/proposal.yaml` · dials density 8, variance 6 · accent #6E2639 on the cover
+rule and the callout rules.
+
+## Purpose
+
+A Proposal asks for approval and money for something that does not exist yet: an investment, a pilot, a
+new service, a funding application, a project plan. Its reader is a decision maker or a panel who wants to
+know what will be done, what it costs, when it happens, what it returns and what could go wrong. Korean
+제안서, 기획서, 사업 계획서 and 투자 품의 fit here.
+
+## Wrong for
+
+- Reporting results of something already running: use a Report.
+- A decision on an existing arrangement, such as a rule change, that fits on two pages: use a Brief.
+- A proposal of one page with no budget table: use a Memo or a Brief.
+
+## Structure
+
+| Feature | What the pack sets |
+|---|---|
+| Page 1 | a typographic cover page: kicker, the title left-aligned in the upper third, one short rule in the accent, the subtitle and the lead; byline, date and notice at the foot; no picture, no colour block |
+| Summary | prose under the first h1, with one key-figure strip after its first paragraph |
+| Numbering | none |
+| Components | keyfigures, callout (one box), columns |
+| Running head | footer: folio centred; the cover has none and the folio starts at 1 on the first body page |
+| Contents | never |
+
+The cover is its own section. The title is broken between words in at most three lines over ten of
+twelve grid columns; the rule under it is 36 mm long and 1 pt thick.
+
+## Type scale
+
+Korean body 10.5 pt, h1 14.5 pt, h2 12.5 pt, title 28.5 pt. English body 11 pt, h1 15.5 pt, h2 13 pt,
+title 29.5 pt. Figures may take up to 60 % of the frame height, the most of any pack, because proposals
+often carry a site plan or a schematic. Korean justified.
+
+## Components
+
+- **Key figures.** One strip in the summary with the three numbers a decision maker weighs: output or
+  benefit, annual saving or revenue, payback or cost per unit. Each basis line states the assumption
+  behind the number. Never on the cover: a strip placed inside the cover directive is moved to the
+  summary.
+- **Callout.** One `kind=key` box with the decision request, normally at the end. The pack caps callouts
+  at one.
+- **Columns.** Two balanced option blocks, when the proposal compares a recommended option with an
+  alternative.
+
+## Writing the source
+
+- Start with a `::: cover kicker="…"` directive whose body is one or two sentences saying what is
+  proposed. That lead is the only text on the cover besides the title block.
+- First h1: the summary. One paragraph on what is proposed and its scale, the strip, one paragraph on cost
+  and timing.
+- Then background (why now), what will be built or done, budget, schedule, benefits and risks, and the
+  decision request.
+- The budget table lists items with amounts in the header unit, a share column and a total row. The
+  schedule table lists stages with dates written the reader's way (`2026년 11월`, `November 2026`).
+- State each risk with its effect on the numbers in the strip ("payback rises to 6.7 years").
+
+## Source fragment
+
+```markdown
+---
+title: 본사 구내 어린이집 정원 확대 제안
+subtitle: 정원 49명에서 79명으로, 2027년 9월 개원
+author: 예시 은행 인사부
+organization: 예시 은행(가상 기업)
+date: 2026-12-01
+notice: 예시 데이터. 회사, 정원, 금액은 모두 가정이다.
+tonality: Proposal
+---
+
+::: cover kicker="복리후생 사업 제안"
+본사 별관 1층을 리모델링해 직장 어린이집 정원을 30명 늘리는 계획이다.
+:::
+
+# 요약
+
+별관 1층 사무 공간 410m²를 보육실 4개와 놀이실로 바꿔 정원을 49명에서 79명으로 늘리자고 제안한다.
+현재 대기 아동은 61명이다.
+
+::: keyfigures
+- **30명** 정원 증가
+  - 만 1~4세, 보육실 4개 기준
+- **6억 8,000만 원** 리모델링·설비 비용
+  - 업체 견적 3건의 중간값
+- **49%** 대기 아동 해소율
+  - 대기 61명 중 30명
+:::
+
+공사는 2027년 3월부터 5개월 동안 진행하고 9월에 새 반을 연다.
+```
+
+## Before delivery
+
+- The cover holds the kicker, title, rule, subtitle, one lead sentence and the foot lines, nothing else.
+- The strip's numbers appear again in the budget table or the text, identical.
+- The decision callout states the amount, the budget line and the first step after approval.
+- The budget table's shares add to 100.0 and its rows add to the total.

package/skills/lit-docx/references/tonalities/report.md

@@ -0,0 +1,126 @@
+# Report
+
+Pack: `templates/tonalities/report.yaml` · dials density 9, variance 5 · accent #1F3A5F on the title rule
+and callout rules.
+
+## Purpose
+
+A Report carries results and the evidence for them: a periodic operating report, a project close-out, an
+analysis of a programme, a quarterly review. It runs from about four to thirty pages, its readers are
+managers who read the summary closely and the rest selectively, and its tables do most of the arguing.
+
+The Korean default follows the manner of a research institute's issue paper: continuous prose in the
+plain declarative style (-다), sections numbered Ⅰ. / 1. / 가., tables with `<표 n>` captions, unit lines
+and source lines. The government 개조식 style (□ ○ - lines ending in -함, -임) is a variant the user must
+ask for; it is not the default.
+
+## Wrong for
+
+- A document that asks for one decision and has fewer than three supporting tables: that is a Brief.
+- A procedure the reader follows step by step: that is a Manual.
+- A request for money or approval of a new project with a budget and schedule: that is a Proposal.
+- One or two pages of notice: that is a Memo.
+- A long argument with few tables, written to be read through: that is a Journal.
+
+## Structure
+
+| Feature | What the pack sets |
+|---|---|
+| Page 1 | masthead title block: series line (kicker left, date right), title, subtitle, byline, one rule in the accent, the notice |
+| Summary | prose under the first h1, with an optional key-figure strip after its first paragraph |
+| Numbering | Korean Ⅰ. / 1. / 가.; English 1 / 1.1 / 1.1.1 |
+| Components | keyfigures, callout, columns (three kinds at most, as always) |
+| Running head | footer: short title left, folio right; none on page 1 |
+| Contents | a short list of h1 headings with page numbers after the title block, when the source is long enough for about five pages |
+
+The contents list is generated from the h1 headings; do not write one in the source. The page estimate is
+about 1,500 Korean or 3,300 English characters per page, plus a line for every table row.
+
+## Type scale
+
+Body 10.5 pt Pretendard, h1 14.5 pt, h2 12.5 pt, h3 10.5 pt bold, title 26.5 pt, table text 9.5 pt,
+note lines 9 pt. Korean body justified, English ragged right. Line pitch 175 % (Korean) and 133 %
+(English) at density 9.
+
+## Components
+
+- **Key figures.** One strip in the summary with three or four results of the period, each with a basis
+  line. Good: trips carried, availability against target, cost per trip. Poor: the number of sites, the
+  project start date.
+- **Callout.** Usually one `kind=key` box for the decision the report asks for, at the end. A report long
+  enough for a second callout (about eight pages) may add one `kind=warning` for a risk that needs action
+  before the next report.
+- **Columns.** Rarely needed. Use for two parallel blocks of similar length, such as two sites or two
+  options, inside a section.
+
+A Report of four pages or more needs two component kinds to pass `component.variety`, because the
+masthead does not count as one. Key figures in the summary and a decision callout are the usual pair.
+
+## Writing the source
+
+- Open with a `::: cover kicker="…"` directive when the report belongs to a series ("운영 보고 2026-4호",
+  "Half-year operating report"); leave it out otherwise.
+- Make the first h1 the summary (요약 / Summary). Its first paragraph states the main result with its
+  number; the strip follows; the next paragraphs give the main problem and what is proposed.
+- Give every following h1 an opening paragraph before its first h2.
+- Put the evidence in tables with captions, a unit line where the header allows it, and `주:` / `자료:`
+  lines. Discuss each table in the text: the sentence before it says what to look for, the sentence after
+  it says what follows from it.
+- End with the plan or decision section; a closing `kind=key` callout states exactly what is asked.
+- Set `short_title:` for the footer.
+
+## Source fragment
+
+```markdown
+---
+title: 2026년 상반기 고객 상담 센터 운영 실적
+subtitle: 응답 시간, 상담 건수, 인력 운영
+author: 예시 서비스 고객지원팀
+organization: 예시 서비스(가상 기업)
+date: 2026-07-10
+short_title: 상반기 상담 센터 실적
+notice: 예시 데이터. 회사와 수치는 모두 가정이다.
+tonality: Report
+---
+
+::: cover kicker="반기 운영 보고"
+:::
+
+# 요약
+
+상반기 상담 건수는 18만 4,200건으로 작년 같은 기간보다 9% 늘었다. 평균 응답 시간은 2분 40초로
+목표 3분 안에 들었지만, 3월 요금 개편 직후 두 주 동안은 6분을 넘었다.
+
+::: keyfigures
+- **18만 4,200건** 상반기 상담 건수
+  - 2026. 1.~6., 전화·채팅 합계
+- **2분 40초** 평균 응답 시간
+  - 목표 3분, 상담 시스템 기록
+- **87%** 1회 해결률
+  - 재문의 7일 기준
+:::
+
+# 상담 건수
+
+상담 건수는 요금 개편이 있었던 3월에 가장 많았다.
+
+표 1. 1분기 월별 상담 건수
+
+| 구분 | 1월 (건) | 2월 (건) | 3월 (건) |
+|---|---:|---:|---:|
+| 전화 | 18,400 | 17,900 | 26,100 |
+| 채팅 | 9,800 | 10,200 | 14,600 |
+
+자료: 상담 시스템 월간 집계(예시)
+```
+
+The three header cells after the first end in the same unit, so the converter writes `(단위: 건)` above
+the table and the headers read 1월, 2월, 3월. The h1 headings print as Ⅰ. 요약 and Ⅱ. 상담 건수.
+
+## Before delivery
+
+- Every number in the summary and the strip matches the table that carries the same quantity, with the
+  same rounding.
+- Headings are noun phrases; no heading ends in -다 or -음.
+- No ISO date outside the frontmatter `date:`.
+- The qa run passes; with `--layout`, no page under 0.35 fill, no stranded heading, no split table.

package/skills/lit-docx/run.py

@@ -20,6 +20,7 @@ COMMANDS = {
     "pdf-to-md": "convert_pdf.py",
     "edit": "edit_docx.py",
     "lint": "slop_lint.py",
+    "qa": "craft_docx.py",
     "audit": "visual_audit.py",
     "clean-md": "clean_markdown.py",
     "embed-images": "embed_images.py",
@@ -48,7 +49,7 @@ def prepare():
 
 def main():
     if len(sys.argv) < 2:
-        raise SystemExit("Usage: python3 run.py <md-to-docx|md-to-pdf|pdf-to-md|edit|lint|audit|clean-md|embed-images|templates|doctor> [arguments]")
+        raise SystemExit("Usage: python3 run.py <md-to-docx|md-to-pdf|pdf-to-md|edit|lint|qa|audit|clean-md|embed-images|templates|doctor> [arguments]")
     command, *args = sys.argv[1:]
     if command == "doctor":
         print(json.dumps({"pythonReady": ready()}))