@litfamily/litclaude 1.0.19 → 1.0.21

package/plugins/litclaude/skills/lit-docx/scripts/qa_docx.py

@@ -14,13 +14,21 @@ The document counterpart of lit-pptx's qa_deck.py. It combines:
   4. Content    — the document has body text, every Markdown heading reached it, no
                   unfilled blank ([제품명], [금액], XXX, TBD, ○○, {{…}}) is left, and
                   no YAML frontmatter leaked into the body
-
-Rendering is separate (visual_audit.py) because it needs soffice; a clean gate
-is defect-absence, not a verdict on how the pages read.
+  5. Output     — docx_layout.py: headings, the title and the subtitle are noun-phrase
+                  labels (heading.declarative), heading levels in order (heading.order),
+                  components counted; with --layout the document is rendered through
+                  soffice and its pages checked: fill.page, heading.stranded, table.split,
+                  figure.split, component.variety and cover.block (FAILs on a tonality document);
+                  the restraint checks of spec Amendments 4 always (color.accent-kinds, heading.ink,
+                  heading.ratio, table.fill, component.budget, furniture.chip on a tonality document;
+                  date.iso on every path); --compare OTHER.docx adds tonality.structure
+
+Without --layout nothing is rendered; visual_audit.py writes the page images to look at.
+A clean gate is defect-absence, not a verdict on how the pages read.
 
 Usage:
+    python3 qa_docx.py out.docx --source draft.md --layout [--kind report]        # tonality or plain
     python3 qa_docx.py out.docx --source draft.md --publisher korean-generic [--kind report]
-    python3 qa_docx.py out.docx --source draft.md                       # plain profile
 
 Prints JSON; exit 0 on PASS, 1 on FAIL.
 """
@@ -34,11 +42,13 @@ _sys.dont_write_bytecode = True  # the installed skill directory stays read-only
 _sys.path.insert(0, _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", "..", "..", "lib"))
 from office_runtime_bootstrap import ensure_runtime  # noqa: E402
 
-ensure_runtime(["docx", "markdown", "bs4", "yaml"])
+ensure_runtime(["docx", "markdown", "bs4", "yaml", "pymupdf"])
 
 import argparse  # noqa: E402
 import json  # noqa: E402
 import re  # noqa: E402
+import subprocess  # noqa: E402
+import tempfile  # noqa: E402
 from pathlib import Path  # noqa: E402
 
 from docx import Document  # noqa: E402
@@ -46,7 +56,10 @@ from ooxml_integrity import check_package  # noqa: E402
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 _sys.path.insert(0, str(SCRIPT_DIR))
+import docx_layout  # noqa: E402
 import slop_lint  # noqa: E402
+from convert_md_to_docx import parse_frontmatter  # noqa: E402
+from render_pages import to_pdf  # noqa: E402
 
 HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
 # A bracket with a digit in it is a citation marker ([1], [S3]); a blank has none.
@@ -79,9 +92,9 @@ def check_content(docx_path: Path, markdown_text: str | None) -> dict:
     leaked = [p for p in paragraphs[:8] if FRONTMATTER_LEAK.match(p)]
     missing = []
     if markdown_text:
-        text = "\n".join(paragraphs)
+        text = docx_layout.norm("".join(paragraphs + cells))  # a heading may stand in a side-by-side columns row
         for heading in source_headings(markdown_text):
-            if heading not in text:
+            if docx_layout.norm(heading) not in text:
                 missing.append(heading)
     return {
         "pass": body_chars > 0 and not missing and not blanks and not leaked,
@@ -94,7 +107,7 @@ def check_content(docx_path: Path, markdown_text: str | None) -> dict:
     }
 
 
-def lint(source: Path | None, docx_path: Path, publisher_name: str, kind: str) -> dict:
+def lint(source: Path | None, docx_path: Path, publisher_name: str, kind: str, explicit_publisher: bool = True) -> dict:
     registry = SCRIPT_DIR.parent / "templates" / "registry.yaml"
     phrase_rules = slop_lint.load_phrase_rules(SCRIPT_DIR.parent / "references" / "slop_phrase_list.yaml")
     publisher = slop_lint.load_publisher(registry, publisher_name)
@@ -105,6 +118,9 @@ def lint(source: Path | None, docx_path: Path, publisher_name: str, kind: str) -
         findings.extend(found)
         if kind == "report":
             findings = [f for f in findings if f.rule_id not in slop_lint.MANUSCRIPT_ONLY_RULES]
+        elif not explicit_publisher:
+            # A tonality or plain manuscript has no publisher outline to follow.
+            findings = [f for f in findings if f.rule_id != "rule-08-structure-order"]
     design = slop_lint.audit_docx_design(docx_path, publisher)
     if locale in {"ko", "mixed"} or source is None:
         design.extend(slop_lint.audit_docx_cjk(docx_path))
@@ -120,6 +136,39 @@ def lint(source: Path | None, docx_path: Path, publisher_name: str, kind: str) -
     }
 
 
+def output_checks(docx_path: Path, source: Path | None, args) -> dict:
+    """docx_layout's checks: structural always, the page checks when --layout renders the document."""
+    front = parse_frontmatter(source.read_text(encoding="utf-8"))[0] if source else {}
+    tonality = bool(args.tonality or front.get("tonality"))
+    info = docx_layout.read_docx(docx_path)
+    found = docx_layout.structural(info, front, args.kind == "manuscript", tonality)
+    found += docx_layout.restraint(docx_path, tonality)
+    result = {"components": info["components"], "rendered": False}
+    if args.compare:
+        mine, other = docx_layout.structure(docx_path), docx_layout.structure(args.compare.expanduser().resolve())
+        differ = docx_layout.structure_diff(mine, other)
+        result["structure"] = {"this": mine, "other": other, "differ": differ}
+        if len(differ) < 3:
+            found.append(docx_layout.finding("tonality.structure", "FAIL", None,
+                                             f"the two documents differ in {len(differ)} structural feature(s): {', '.join(differ) or 'none'} (at least 3)",
+                                             "Two tonalities differ in structure, not colour: title block, summary form, numbering, component set, running head, contents."))
+    if args.layout:
+        with tempfile.TemporaryDirectory(prefix="lit-docx-layout-") as tmp:
+            try:
+                pdf, how = to_pdf(docx_path, Path(tmp))
+            except (RuntimeError, subprocess.TimeoutExpired) as error:
+                pdf, how = None, f"render failed: {error}"
+            if pdf is None:
+                result["render"] = how  # the reply must say the page checks did not run
+            else:
+                page_found, pages = docx_layout.paged(info, docx_layout.read_pdf(pdf), tonality, front)
+                found += page_found
+                result.update(pages, rendered=True)
+    result["findings"] = [f for f in found if f["severity"] == "FAIL"]
+    result["advisories"] = [f for f in found if f["severity"] != "FAIL"]
+    return result
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Pass/fail gate for a generated DOCX.")
     parser.add_argument("docx", type=Path)
@@ -130,6 +179,9 @@ def main(argv: list[str] | None = None) -> int:
         help="Profile the DOCX was built with (korean-generic, elsevier, acs, ieee, nature). Omit for the plain profile.",
     )
     parser.add_argument("--kind", choices=("report", "manuscript"), default="report")
+    parser.add_argument("--layout", action="store_true", help="render through soffice and check the pages (fill, stranded headings, splits, component variety)")
+    parser.add_argument("--tonality", default=None, help="the tonality the DOCX was built with, when the source frontmatter does not name it")
+    parser.add_argument("--compare", type=Path, default=None, help="the same source built in another tonality: fail when the two differ in fewer than three structural features")
     args = parser.parse_args(argv)
 
     docx_path = args.docx.expanduser().resolve()
@@ -139,12 +191,14 @@ def main(argv: list[str] | None = None) -> int:
     # The plain profile has no registry entry; its prose is still linted with the
     # korean-generic phrase rules, and the design audit is limited to what every
     # profile shares.
-    lint_report = lint(source, docx_path, args.publisher or "korean-generic", args.kind) if integrity["pass"] else {"pass": False}
+    lint_report = lint(source, docx_path, args.publisher or "korean-generic", args.kind, args.publisher is not None) if integrity["pass"] else {"pass": False}
     if args.publisher is None and lint_report.get("design"):
         shared = {"rule-45-highlighted-text", "rule-46-tracked-changes", "rule-55-ellipsis", "rule-60-numeric-column-alignment"}
         lint_report["design"] = [f for f in lint_report["design"] if f["rule"] in shared]
         lint_report["pass"] = not lint_report["prose"] and not lint_report["design"]
 
+    output = output_checks(docx_path, source, args) if integrity["pass"] else {"findings": [], "advisories": []}
+
     reasons = []
     if not integrity["pass"]:
         reasons.append("integrity: " + "; ".join(integrity["problems"][:5]))
@@ -158,6 +212,8 @@ def main(argv: list[str] | None = None) -> int:
         reasons.append(f"prose lint: {len(lint_report['prose'])} finding(s)")
     if lint_report.get("design"):
         reasons.append(f"design audit: {len(lint_report['design'])} finding(s)")
+    if output["findings"]:
+        reasons.append(f"output checks: {', '.join(sorted({f['check'] for f in output['findings']}))}")
 
     report = {
         "file": str(docx_path),
@@ -168,6 +224,7 @@ def main(argv: list[str] | None = None) -> int:
         "integrity": {"pass": integrity["pass"], "problems": integrity["problems"][:20]},
         "content": content,
         "lint": lint_report,
+        "output": output,
     }
     print(json.dumps(report, ensure_ascii=False, indent=2))
     return 0 if report["pass"] else 1

package/plugins/litclaude/skills/lit-docx/scripts/slop_lint.py

@@ -102,6 +102,9 @@ def word_count(text: str) -> int:
     return len(re.findall(r"\b[\w’'-]+\b", text))
 
 
+TITLE_MINOR = {"a", "an", "the", "and", "but", "or", "nor", "for", "of", "in", "on", "at", "to", "by", "as", "via", "with", "from"}
+
+
 def heading_case_ok(heading: str, expected: str) -> bool:
     bare = heading.strip()
     if not bare:
@@ -111,8 +114,9 @@ def heading_case_ok(heading: str, expected: str) -> bool:
     if expected == "sentence_case":
         return bare[0].isupper() and bare[1:] != bare[1:].upper()
     if expected == "title_case":
-        words = [w for w in re.findall(r"[A-Za-z][A-Za-z'-]*", bare)]
-        return all(word[0].isupper() for word in words[: min(len(words), 6)]) if words else True
+        # Title case capitalises every word except a short article, conjunction or preposition after the first.
+        words = [w for w in re.findall(r"[A-Za-z][A-Za-z'-]*", bare)][:6]
+        return all(word[0].isupper() or (i and word in TITLE_MINOR) for i, word in enumerate(words)) if words else True
     return True
 
 
@@ -207,7 +211,11 @@ def lint_text(md_text: str, publisher: dict, phrase_rules: dict, locale: str) ->
                 for match in re.finditer(re.escape(phrase), section_text):
                     add_finding(findings, full_text, offsets, section_pos + match.start(), "rule-21-ko-ai-phrase", section_name, f"한국어 AI 표현: '{match.group(0)}'", match.group(0))
 
-        if section_text.count("—") >= 2 or section_text.count(" - ") >= 1:
+        # A spaced hyphen between words reads as a dash; one opening a line is a list marker
+        # (a key figure's basis line, a nested point), not a dash.
+        # Table rows are data: a dash there marks an empty cell.
+        prose = "\n".join(line for line in section_text.split("\n") if not line.lstrip().startswith("|"))
+        if prose.count("—") >= 2 or re.search(r"\S - ", prose):
             add_finding(findings, full_text, offsets, max(section_pos, 0), "rule-02-em-dash-cluster", section_name, "Paragraph uses dash-heavy rhetorical style", section_text[:120])
 
         sentences = sentence_split(section_text)
@@ -252,7 +260,8 @@ def lint_text(md_text: str, publisher: dict, phrase_rules: dict, locale: str) ->
                 for match in re.finditer(re.escape(phrase), section_text):
                     add_finding(findings, full_text, offsets, section_pos + match.start(), "rule-24-ko-loanword", section_name, f"외래어 남용 감지: '{match.group(0)}'", match.group(0))
 
-        if len(lengths) >= 4 and wc >= 80:
+        # A reference list is a run of entries, not prose.
+        if len(lengths) >= 4 and wc >= 80 and section_name.strip().lower() not in REFERENCE_SECTIONS:
             mean = sum(lengths) / len(lengths)
             variance = sum((item - mean) ** 2 for item in lengths) / len(lengths)
             if variance ** 0.5 < 6:
@@ -274,8 +283,10 @@ def lint_text(md_text: str, publisher: dict, phrase_rules: dict, locale: str) ->
         if total_words >= 250 and section_name.lower() == "methods" and section_ratio < 0.15:
             add_finding(findings, full_text, offsets, max(section_pos, 0), "rule-09-section-balance", section_name, "Methods section is too small relative to the manuscript", section_text[:120])
 
-        ttr = type_token_ratio(section_text)
-        if ttr < 0.45 and wc > 40:
+        # TTR falls with length, so it is read per subsection (the smallest headed unit), not over a whole chapter.
+        parts = [part for part in re.split(r"(?m)^(?=#{2,6} )", section_text) if word_count(part) > 40]
+        ttr = min((type_token_ratio(part) for part in parts), default=1.0)
+        if ttr < 0.45:
             add_finding(findings, full_text, offsets, max(section_pos, 0), "rule-10-lexical-diversity", section_name, f"Lexical diversity is low (TTR={ttr:.2f})", section_text[:120])
 
         for pattern in adjective_stacks:
@@ -485,6 +496,7 @@ def parse_args() -> argparse.Namespace:
 
 # Rules that describe a journal manuscript's shape. A business report, proposal or plan
 # has no Introduction/Methods outline to follow, so --kind report leaves them out.
+REFERENCE_SECTIONS = {"references", "reference", "bibliography", "참고문헌", "참고 문헌"}
 MANUSCRIPT_ONLY_RULES = {"rule-07-citation-density", "rule-08-structure-order", "rule-09-section-balance"}
 
 

package/plugins/litclaude/skills/lit-docx/templates/tonalities/brief.yaml

@@ -0,0 +1,28 @@
+# Brief: a one-to-three page briefing for a decision maker. Conclusion first: the decision request stands right
+# under a compact title block, the summary is a run of numbered points (①-④, a bold lead sentence then plain
+# text), sections stay unnumbered and open under a full-width hairline, one box at most, and only the folio
+# runs at the foot.
+schema_version: 2
+tonality: Brief
+summary: One-to-three page briefings for a decision maker, conclusion first
+dials: {density: 9, variance: 3}
+docx:
+  page: {size: A4}
+  font: {latin: Pretendard, hangul: Pretendard, heading: Pretendard, body_pt_ko: 10.5, body_pt_en: 10.5}
+design:
+  ramp: {h1: 1.3, h2: 1.15, title: 2.5}
+  numbering: none
+  h1_rule: above
+  title_block: masthead
+  contents: false
+  summary_form: points
+  conclusion_first: true
+  running_head: {footer: [folio], folio_align: right}
+  justify: ko
+  palette: {ink: "1A1A1A", ink_muted: "555555", line: "8C8C8C", accent: "2D5A47"}
+  accent_on: [title_rule, callout_rule]
+  page_geometry: {columns: 1, column_gap_cm: 0.6}
+  components:
+    allowed: [callout, columns]
+    callout_max: 1
+  figure_style: {max_height_ratio: 0.40}

package/plugins/litclaude/skills/lit-docx/templates/tonalities/journal.yaml

@@ -0,0 +1,25 @@
+# Journal: long-form reading in two columns (essays, newsletters, white papers, research summaries not bound
+# for a named journal), close to a publisher profile: a title block with authors, abstract and keywords,
+# decimal section numbers for cross-references, Latin body text in Times New Roman (Hangul and headings in
+# Pretendard), ragged right, the short title and folio in the header.
+schema_version: 2
+tonality: Journal
+summary: Long-form reading in two columns, for essays, newsletters, white papers and research summaries
+dials: {density: 9, variance: 6}
+docx:
+  page: {size: A4}
+  font: {latin: Times New Roman, hangul: Pretendard, heading: Pretendard, body_pt_ko: 10.5, body_pt_en: 10.5}
+design:
+  ramp: {h1: 1.3, h2: 1.15, title: 2.5}
+  numbering: decimal
+  title_block: masthead
+  contents: false
+  summary_form: prose
+  running_head: {header: [title, folio]}
+  justify: none
+  palette: {ink: "1A1A1A", ink_muted: "555555", line: "8C8C8C"}
+  accent_on: []
+  page_geometry: {columns: 2, column_gap_cm: 0.6}
+  components:
+    allowed: [callout]
+  figure_style: {max_height_ratio: 0.40}

package/plugins/litclaude/skills/lit-docx/templates/tonalities/manual.yaml

@@ -0,0 +1,26 @@
+# Manual: a technical guide or procedure. The title over a document-control block (document, owner,
+# organisation, issued), a short contents list, decimal sections 1 / 1.1, numbered steps, one warning style
+# for every callout, an optional sidebar beside the text, the short title in the header and the folio at the
+# foot.
+schema_version: 2
+tonality: Manual
+summary: How-to guides, procedures and operating manuals with steps, warnings and reference tables
+dials: {density: 9, variance: 6}
+docx:
+  page: {size: A4}
+  font: {latin: Pretendard, hangul: Pretendard, heading: Pretendard, body_pt_ko: 10.5, body_pt_en: 10.5}
+design:
+  ramp: {h1: 1.35, h2: 1.15, title: 2.5}
+  numbering: decimal
+  title_block: manual
+  contents: true
+  summary_form: prose
+  running_head: {header: [title], footer: [folio], folio_align: right}
+  justify: none
+  palette: {ink: "1A1A1A", ink_muted: "555555", line: "8C8C8C", accent: "2E4A66"}
+  accent_on: [callout_rule, sidebar_rule]
+  page_geometry: {columns: 1, column_gap_cm: 0.6}
+  components:
+    allowed: [callout, sidebar, columns]
+    sidebar: {default_width: third, float: right}
+  figure_style: {max_height_ratio: 0.45}

package/plugins/litclaude/skills/lit-docx/templates/tonalities/memo.yaml

@@ -0,0 +1,26 @@
+# Memo: a notice, internal memo, short decision request or letter of one to two pages. No cover: a label, the
+# subject as title and To / From / Date / Subject rows between two hairlines; no components (a callout reads as
+# a bold lead line); unnumbered sections; the folio from page 2.
+schema_version: 2
+tonality: Memo
+summary: Notices, internal memos, short decision requests and letters of one to two pages
+dials: {density: 9, variance: 2}
+docx:
+  page: {size: A4}
+  font: {latin: Pretendard, hangul: Pretendard, heading: Pretendard, body_pt_ko: 10.5, body_pt_en: 11}
+design:
+  ramp: {h1: 1.2, h2: 1.1, title: 1.8}
+  numbering: none
+  title_block: memo
+  contents: false
+  summary_form: prose
+  running_head: {footer: [folio], folio_align: right}
+  justify: ko
+  palette: {ink: "1A1A1A", ink_muted: "555555", line: "8C8C8C"}
+  accent_on: []
+  page_geometry: {columns: 1, column_gap_cm: 0.6}
+  components:
+    allowed: []
+  figure_style: {max_height_ratio: 0.40}
+  # A memo stays on one page when its content allows: the low end of the line pitch, tighter heading space.
+  spacing: tight

package/plugins/litclaude/skills/lit-docx/templates/tonalities/proposal.yaml

@@ -0,0 +1,26 @@
+# Proposal: a proposal or plan as a document. A typographic cover page (the title left-aligned in the upper
+# third, one short rule, the byline and date at its foot; no colour block, no figures), unnumbered sections,
+# one decision box, key figures once in the summary, a budget table, the folio centred at the foot.
+schema_version: 2
+tonality: Proposal
+summary: Proposals, plans and pitches as documents, with a cover, a decision box, budget and schedule
+dials: {density: 8, variance: 6}
+docx:
+  page: {size: A4}
+  font: {latin: Pretendard, hangul: Pretendard, heading: Pretendard, body_pt_ko: 10.5, body_pt_en: 11}
+design:
+  ramp: {h1: 1.4, h2: 1.2, title: 2.7}
+  numbering: none
+  title_block: cover
+  contents: false
+  summary_form: prose
+  running_head: {footer: [folio], folio_align: center}
+  justify: ko
+  palette: {ink: "1A1A1A", ink_muted: "555555", line: "8C8C8C", accent: "6E2639"}
+  accent_on: [title_rule, callout_rule]
+  page_geometry: {columns: 1, column_gap_cm: 0.6}
+  components:
+    allowed: [keyfigures, callout, columns]
+    callout_max: 1
+    keyfigures: {per_row: 3}
+  figure_style: {max_height_ratio: 0.60}

package/plugins/litclaude/skills/lit-docx/templates/tonalities/report.yaml

@@ -0,0 +1,26 @@
+# Report: periodic results, project reports and analyses read by managers; 4-30 pages, tables carry the evidence.
+# Korean default is institute prose (the manner of a central-bank or think-tank issue note): a typographic title
+# block on page 1, a short contents list from five pages, sections numbered Ⅰ. / 1. / 가. (English 1 / 1.1),
+# booktabs tables with <표 n> captions, units and 자료 lines, a footer with the short title and the folio.
+schema_version: 2
+tonality: Report
+summary: Periodic results, project reports and analyses with tables and figures
+dials: {density: 9, variance: 5}
+docx:
+  page: {size: A4}
+  font: {latin: Pretendard, hangul: Pretendard, heading: Pretendard, body_pt_ko: 10.5, body_pt_en: 10.5}
+design:
+  ramp: {h1: 1.4, h2: 1.2, title: 2.5}
+  numbering: {ko: roman-ko, en: decimal}
+  title_block: masthead
+  contents: true
+  summary_form: prose
+  running_head: {footer: [title, folio]}
+  justify: ko
+  palette: {ink: "1A1A1A", ink_muted: "555555", line: "8C8C8C", accent: "1F3A5F"}
+  accent_on: [title_rule, callout_rule]
+  page_geometry: {columns: 1, column_gap_cm: 0.6}
+  components:
+    allowed: [keyfigures, callout, columns]
+    keyfigures: {per_row: 3}
+  figure_style: {max_height_ratio: 0.45}