devlyn-cli 0.5.1 → 0.5.3

package/optional-skills/dokkit/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: dokkit
+description: >
+  Document template filling system for DOCX and HWPX formats.
+  Ingests source documents, analyzes templates, detects fillable fields,
+  fills them surgically using source data, reviews with confidence scoring,
+  and exports completed documents. Supports Korean and English templates.
+  Subcommands: init, sources, preview, ingest, fill, fill-doc, modify, review, export.
+  Use when user says "fill template", "fill document", "ingest", "dokkit".
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+argument-hint: "<subcommand> [arguments]"
+context:
+  - type: file
+    path: ${CLAUDE_SKILL_DIR}/COMMANDS.md
+---
+
+# Dokkit — Document Template Filling System
+
+Surgical document filling for DOCX and HWPX templates using ingested source data. One command with 9 subcommands covering the full document filling lifecycle.
+
+## Subcommands
+
+| Subcommand | Arguments | Type | Description |
+|------------|-----------|------|-------------|
+| `init` | `[--force] [--keep-sources]` | Inline | Initialize or reset workspace |
+| `sources` | — | Inline | Display ingested sources dashboard |
+| `preview` | — | Inline | Generate PDF preview via LibreOffice |
+| `ingest` | `<file1> [file2] ...` | Agent | Parse source documents into workspace |
+| `fill` | `<template.docx\|hwpx>` | Agent | End-to-end: analyze, fill, review, auto-fix, export |
+| `fill-doc` | `<template.docx\|hwpx>` | Agent | Analyze template and fill fields only |
+| `modify` | `"<instruction>"` | Agent | Apply targeted changes to filled document |
+| `review` | `[section\|approve]` | Agent | Review with per-field confidence annotations |
+| `export` | `<docx\|hwpx\|pdf>` | Agent | Export filled document to format |
+
+## Routing
+
+Parse `$ARGUMENTS` to determine the subcommand:
+
+1. Extract `$1` as the subcommand name
+2. Pass remaining arguments (`$2`, `$3`, ...) to the subcommand
+3. If `$1` is empty or unrecognized, display the subcommand table above with usage examples
+
+Full workflows for each subcommand are in COMMANDS.md (auto-loaded via context).
+
+<example>
+- `/dokkit ingest docs/resume.pdf docs/transcript.xlsx` — ingest two sources
+- `/dokkit fill docs/template.hwpx` — end-to-end fill pipeline
+- `/dokkit modify "Change the phone number to 010-1234-5678"` — targeted change
+- `/dokkit export pdf` — export as PDF
+</example>
+
+## Architecture
+
+### Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| **dokkit-ingestor** | opus | Parse source docs into `.dokkit/sources/` (.md + .json pairs) |
+| **dokkit-analyzer** | opus | Analyze templates, detect fields, map to sources. Writes `analysis.json`. READ-ONLY on templates. |
+| **dokkit-filler** | opus | Surgical XML modification using analysis.json. Three modes: fill, modify, review. |
+| **dokkit-exporter** | sonnet | Repackage ZIP archives, PDF conversion via LibreOffice. |
+
+### Workspace
+
+All agents communicate via the `.dokkit/` filesystem:
+
+```
+.dokkit/
+├── state.json          # Single source of truth for session state
+├── sources/            # Ingested content (.md + .json pairs)
+├── analysis.json       # Template analysis output (from analyzer)
+├── images/             # Sourced images for template filling
+├── template_work/      # Unpacked template XML (working copy)
+└── output/             # Exported filled documents
+```
+
+### State Protocol
+
+Read `.dokkit/state.json` before any operation. Write state changes atomically: read current → update fields → write back → validate.
+
+```
+init → state created (empty)
+ingest → source added to sources[]
+fill/fill-doc → template set, analysis created, filled_document created
+modify → filled_document updated
+review approve → filled_document.status = "finalized"
+export → export entry added to exports[]
+```
+
+Validate after every write: `python ${CLAUDE_SKILL_DIR}/scripts/validate_state.py .dokkit/state.json`
+
+### Knowledge Files
+
+Agent-facing knowledge bases in this skill directory:
+
+| File | Purpose | Agents |
+|------|---------|--------|
+| `STATE.md` | State schema and management protocol | All |
+| `INGESTION.md` | Format routing and parsing strategies | dokkit-ingestor |
+| `ANALYSIS.md` | Field detection, confidence scoring, output schema | dokkit-analyzer |
+| `FILLING.md` | XML surgery rules, matching strategy, image insertion | dokkit-analyzer, dokkit-filler |
+| `DOCX-XML.md` | Open XML structure for DOCX documents | dokkit-analyzer, dokkit-filler |
+| `HWPX-XML.md` | OWPML structure for HWPX documents | dokkit-analyzer, dokkit-filler |
+| `IMAGE-SOURCING.md` | Image generation, search, and insertion patterns | dokkit-filler |
+| `EXPORT.md` | Document compilation and format conversion | dokkit-exporter |
+
+Deep reference material in `references/`:
+- `state-schema.md` — Complete state.json schema
+- `supported-formats.md` — Detailed format specifications
+- `docx-structure.md`, `docx-field-patterns.md` — DOCX patterns
+- `hwpx-structure.md`, `hwpx-field-patterns.md` — HWPX patterns (10 detection patterns)
+- `field-detection-patterns.md` — Advanced heuristics (9 DOCX + 6 HWPX)
+- `section-range-detection.md` — Dynamic range detection for section_content
+- `section-image-interleaving.md` — Image interleaving algorithm
+- `image-opportunity-heuristics.md` — AI image opportunity detection
+- `image-xml-patterns.md` — Image element structures (DOCX + HWPX)
+
+Scripts in `scripts/`:
+- `validate_state.py` — State validation
+- `parse_xlsx.py`, `parse_hwpx.py`, `parse_image_with_gemini.py` — Custom parsers
+- `detect_fields.py`, `detect_fields_hwpx.py` — Field detection
+- `validate_docx.py`, `validate_hwpx.py` — Document validation
+- `compile_hwpx.py` — HWPX repackaging
+- `export_pdf.py` — PDF conversion
+
+## Rules
+
+<rules>
+- Display errors clearly with actionable guidance. Never silently fall back to defaults.
+- Original template is never modified — copies go to `.dokkit/template_work/`.
+- Analyzer is read-only on templates. Only the filler modifies XML.
+- Confidence levels: high, medium, low (not numeric scores).
+- Signatures must be user-provided — never auto-generate them.
+- Validate state after every write with `scripts/validate_state.py`.
+- Inline commands (init, sources, preview) execute directly — do NOT spawn agents.
+- Agent-delegated commands spawn the appropriate agent(s) sequentially.
+</rules>
+
+## Known Pitfalls
+
+Critical issues discovered through production use:
+
+1. **HWPX namespace stripping**: Python ET strips unused namespace declarations. Restore ALL 14 original xmlns on EVERY root element after any `tree.write()`. Applies to section0.xml, content.hpf, header.xml.
+2. **HWPX subList cell wrapping**: ~65% of cells wrap content in `<hp:subList>/<hp:p>`. Check for subList before writing content.
+3. **table_content "Pre-filled" bug**: Never set `mapped_value` to placeholder strings for `table_content` fields. Use `mapped_value: null` with `action: "preserve"`.
+4. **HWPX cellAddr rowAddr corruption**: After row insert/delete, re-index ALL `rowAddr` values. Duplicate rowAddr causes silent data loss.
+5. **HWPX `<hp:pic>` inside `<hp:run>`**: Pic as sibling of run renders invisible. Must be `<hp:run><hp:pic>...<hp:t/></hp:run>`.
+6. **HWPML units**: 1/7200 inch, NOT hundredths of mm. 1mm ~ 283.46 units. A4 text width ~ 46,648 units.
+7. **rowSpan stripping**: When cloning rows with rowSpan>1, divide cellSz height by rowSpan.
+8. **HWPX pic element order**: offset, orgSz, curSz, flip, rotationInfo, renderingInfo, imgRect, imgClip, inMargin, imgDim, hc:img, sz, pos, outMargin.
+9. **HWPX post-write safety**: After ET write: (a) restore namespaces, (b) fix XML declaration to double quotes with `standalone="yes"`, (c) remove newline between `?>` and `<root>`.
+10. **compile_hwpx.py skip .bak**: Backup files must be excluded from ZIP repackaging.

package/optional-skills/dokkit/STATE.md

@@ -0,0 +1,60 @@
+# State Management
+
+Protocol for reading and writing `.dokkit/state.json`. All agents follow this protocol.
+
+## Workspace Structure
+
+```
+.dokkit/
+├── state.json          # Single source of truth for session state
+├── sources/            # Ingested source content
+│   ├── <name>.md       # Extracted content (LLM-optimized markdown)
+│   └── <name>.json     # Structured metadata sidecar
+├── analysis.json       # Template analysis output (from analyzer)
+├── images/             # Sourced images
+├── template_work/      # Unpacked template XML (working copy)
+│   ├── word/           # (DOCX) or Contents/ (HWPX)
+│   └── ...
+└── output/             # Exported filled documents
+    └── filled_<name>.<ext>
+```
+
+## Reading State
+
+Read `.dokkit/state.json` before any operation. Check:
+- `sources` array for available context
+- `template` for current template info
+- `analysis` for field mapping data
+- `filled_document` for current document status
+
+## Writing State
+
+After any mutation:
+1. Read current state.json (avoid overwriting concurrent changes)
+2. Update only the relevant fields
+3. Write the full state back
+4. Validate: `python .claude/skills/dokkit/scripts/validate_state.py .dokkit/state.json`
+
+## State Transitions
+
+```
+/dokkit init → state created (empty)
+/dokkit ingest → source added to sources[]
+/dokkit fill or fill-doc → template set, analysis created, filled_document created
+/dokkit modify → filled_document updated
+/dokkit review approve → filled_document.status = "finalized"
+/dokkit export → export entry added to exports[]
+```
+
+## Validation
+
+The validator checks:
+- Schema conformance
+- Required fields present
+- Valid status values
+- Source file references exist
+- No orphaned entries
+
+## References
+
+See `references/state-schema.md` for the complete schema definition.

package/optional-skills/dokkit/references/docx-field-patterns.md

@@ -0,0 +1,151 @@
+# DOCX Field Detection Patterns
+
+## Pattern 1: Placeholder Text
+
+```xml
+<!-- Text like {{name}} or <<name>> in a run -->
+<w:r>
+  <w:rPr>
+    <w:rFonts w:ascii="Arial" w:hAnsi="Arial"/>
+    <w:sz w:val="20"/>
+  </w:rPr>
+  <w:t>{{full_name}}</w:t>  <!-- REPLACE this text content -->
+</w:r>
+```
+
+**Action**: Replace the text content of `<w:t>` while preserving `<w:rPr>`.
+
+## Pattern 2: Empty Table Cell
+
+```xml
+<w:tr>
+  <w:tc>
+    <w:p><w:r><w:t>Name</w:t></w:r></w:p>  <!-- Label cell -->
+  </w:tc>
+  <w:tc>
+    <w:p/>  <!-- Empty cell → FILL THIS -->
+  </w:tc>
+</w:tr>
+```
+
+**Action**: Insert `<w:r><w:t>value</w:t></w:r>` into the empty `<w:p>`. Copy `<w:rPr>` from the label cell's run to match formatting.
+
+## Pattern 3: Underline Placeholder
+
+```xml
+<w:r>
+  <w:rPr>
+    <w:u w:val="single"/>
+  </w:rPr>
+  <w:t xml:space="preserve">          </w:t>  <!-- Spaces with underline -->
+</w:r>
+```
+
+**Action**: Replace the spaces in `<w:t>` with the actual value. Keep `<w:u>` in `<w:rPr>`.
+
+## Pattern 4: Content Control
+
+```xml
+<w:sdt>
+  <w:sdtPr>
+    <w:alias w:val="Company Name"/>
+    <w:tag w:val="company"/>
+    <w:showingPlcHdr/>  <!-- Indicates placeholder is showing -->
+  </w:sdtPr>
+  <w:sdtContent>
+    <w:p>
+      <w:r>
+        <w:rPr><w:rStyle w:val="PlaceholderText"/></w:rPr>
+        <w:t>Click here to enter text.</w:t>
+      </w:r>
+    </w:p>
+  </w:sdtContent>
+</w:sdt>
+```
+
+**Action**: Replace the run inside `<w:sdtContent>` with a new run containing the value. Remove `<w:showingPlcHdr/>` from `<w:sdtPr>`. Remove the placeholder style from `<w:rPr>`.
+
+## Pattern 5: Instruction Text
+
+```xml
+<w:r>
+  <w:rPr>
+    <w:color w:val="808080"/>  <!-- Gray text -->
+    <w:i/>                      <!-- Italic -->
+  </w:rPr>
+  <w:t>(enter your name)</w:t>
+</w:r>
+```
+
+**Action**: Replace text content. Change `<w:rPr>` to remove gray color and italic (or copy from a nearby filled field).
+
+## Pattern 6: Writing Tip Box (작성 팁)
+
+Single-cell tables with dashed borders containing `※` guidance text. These are NOT fillable — they must be **deleted**.
+
+```xml
+<w:tbl>
+  <w:tblPr>
+    <w:tblBorders>
+      <w:top w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+      <w:left w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+      <w:bottom w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+      <w:right w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+    </w:tblBorders>
+  </w:tblPr>
+  <w:tr>
+    <w:tc>
+      <w:p>
+        <w:r>
+          <w:rPr><w:color w:val="FF0000"/></w:rPr>
+          <w:t>※ 작성 팁: 구체적인 사업 목표를 기재하세요.</w:t>
+        </w:r>
+      </w:p>
+    </w:tc>
+  </w:tr>
+</w:tbl>
+```
+
+**Identifying traits**:
+- Single row, single cell (`<w:tr>` has one `<w:tc>`)
+- `<w:tblBorders>` with `w:val="dashed"` on all sides
+- Text starts with `※` or contains `작성 팁`, `작성요령`
+- Often has red `<w:color w:val="FF0000"/>` styling
+
+**Action**: Flag as `field_type: "tip_box"`, `action: "delete"`. Delete the entire `<w:tbl>` element.
+
+## Color Warning for Copied Formatting
+
+When copying `<w:rPr>` from template guide text or instruction text (Patterns 2 and 5), **always check for red color**:
+
+```xml
+<!-- DANGER: This rPr has red color from guide text -->
+<w:rPr>
+  <w:color w:val="FF0000"/>  <!-- REMOVE THIS -->
+  <w:i/>                      <!-- REMOVE THIS (from guide text) -->
+  <w:sz w:val="20"/>          <!-- KEEP -->
+</w:rPr>
+```
+
+**Rule**: After copying rPr from any template text, check for `<w:color>` elements. If the value is `FF0000`, `FF0000FF`, or any red shade, **remove the `<w:color>` element** (defaults to black). Also remove `<w:i/>` if it came from guide text.
+
+## Safe Modification Template
+
+```python
+import xml.etree.ElementTree as ET
+
+ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
+ET.register_namespace("w", ns["w"])
+
+tree = ET.parse("word/document.xml")
+
+# Find and replace placeholder text
+for t_elem in tree.iter("{%s}t" % ns["w"]):
+    if t_elem.text and "{{" in t_elem.text:
+        placeholder = t_elem.text  # e.g., "{{name}}"
+        field_name = placeholder.strip("{}").strip("<>")
+        if field_name in field_values:
+            t_elem.text = field_values[field_name]
+
+tree.write("word/document.xml", xml_declaration=True, encoding="UTF-8")
+```

package/optional-skills/dokkit/references/docx-structure.md

@@ -0,0 +1,58 @@
+# DOCX XML Structure Reference
+
+## Unpacking a DOCX
+
+```bash
+# Unzip to inspect
+mkdir -p .dokkit/template_work
+cd .dokkit/template_work
+unzip -o /path/to/template.docx
+```
+
+## Reading document.xml
+
+The main content is in `word/document.xml`. Parse with any XML parser.
+
+### Python Example
+```python
+import xml.etree.ElementTree as ET
+
+ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
+tree = ET.parse("word/document.xml")
+root = tree.getroot()
+
+# Find all paragraphs
+for p in root.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p"):
+    texts = []
+    for t in p.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t"):
+        if t.text:
+            texts.append(t.text)
+    print("".join(texts))
+```
+
+## Repackaging a DOCX
+
+After modifying XML, repackage as a valid DOCX:
+
+```python
+import zipfile
+import os
+
+def repackage_docx(work_dir, output_path):
+    """Repackage modified XML files into a valid DOCX."""
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:
+        for root, dirs, files in os.walk(work_dir):
+            for file in files:
+                file_path = os.path.join(root, file)
+                arcname = os.path.relpath(file_path, work_dir)
+                zf.write(file_path, arcname)
+```
+
+## Critical Rules for DOCX Surgery
+
+1. **Never remove `<w:rPr>` elements** — they contain all formatting
+2. **Preserve `xml:space="preserve"`** on `<w:t>` elements with leading/trailing spaces
+3. **Keep `<w:pPr>` intact** — paragraph formatting must not change
+4. **Maintain bookmark pairs** — `<w:bookmarkStart>` must have matching `<w:bookmarkEnd>`
+5. **Don't modify `<w:sectPr>`** — section properties control page layout
+6. **Preserve table cell merge attributes** — `<w:vMerge>` and `<w:gridSpan>`

package/optional-skills/dokkit/references/field-detection-patterns.md

@@ -0,0 +1,130 @@
+# Field Detection Patterns
+
+## DOCX Detection Heuristics
+
+### Heuristic 1: Curly Brace Placeholders
+```regex
+\{\{[^}]+\}\}
+```
+Match text like `{{field_name}}`. High reliability.
+
+### Heuristic 2: Angle Bracket Placeholders
+```regex
+<<[^>]+>>
+```
+Match text like `<<field_name>>`. High reliability.
+
+### Heuristic 3: Square Bracket Placeholders
+```regex
+\[[^\]]+\]
+```
+Match text like `[field_name]`. Medium reliability (may match references).
+
+### Heuristic 4: Underline-Only Runs
+A run where:
+- `<w:rPr>` contains `<w:u w:val="single"/>`
+- `<w:t>` contains only spaces, underscores, or is empty
+- Run length > 3 characters
+
+### Heuristic 5: Empty Table Cells
+A `<w:tc>` that:
+- Contains only `<w:p/>` or `<w:p><w:pPr/></w:p>` (empty paragraph)
+- Is adjacent to a cell containing text (the label)
+- The label cell's text is short (< 50 chars) and not numeric
+
+### Heuristic 6: Instruction Text
+A run where text matches patterns like:
+```regex
+\(.*?(enter|type|input|write|fill|입력).*?\)
+```
+
+### Heuristic 7: Content Controls
+Any `<w:sdt>` element with `<w:showingPlcHdr/>` in its properties.
+
+### Heuristic 8: Image Fields
+A field is classified as `image` when any of these conditions hold:
+- A `{{placeholder}}` or `<<placeholder>>` contains an image keyword
+- A table cell contains an existing `<w:drawing>` element (pre-positioned image slot)
+- An empty table cell is adjacent to a cell whose label matches an image keyword
+
+**Image keywords** (case-insensitive):
+- Korean: 사진, 증명사진, 여권사진, 로고, 서명, 날인, 도장, 직인
+- English: Photo, Picture, Logo, Signature, Stamp, Seal, Image, Portrait
+
+**Image type classification**:
+| Keyword match | `image_type` |
+|---------------|-------------|
+| 사진, 증명사진, 여권사진, photo, picture, portrait, image | `photo` |
+| 로고, logo | `logo` |
+| 서명, 날인, 도장, 직인, signature, stamp, seal | `signature` |
+| (no keyword match) | `figure` |
+
+Image fields are **excluded** from the `placeholder_text` and `empty_cell` detectors to prevent double-detection.
+
+### Heuristic 9: Tip Box
+A `<w:tbl>` that:
+- Has exactly one row and one cell (1×1 table)
+- `<w:tblBorders>` uses `w:val="dashed"` borders
+- Cell text starts with `※` or contains `작성 팁` / `작성요령`
+- Often has red text color (`<w:color w:val="FF0000"/>`)
+
+→ `field_type: "tip_box"`, `action: "delete"`
+
+## HWPX Detection Heuristics
+
+### Heuristic 1: Empty Adjacent Cells
+Same as DOCX but using `<hp:tc>` and `<hp:t>` elements.
+
+### Heuristic 2: Korean Instruction Text
+```regex
+\(.*?(입력|기재|작성).*?\)
+```
+
+### Heuristic 3: Date Component Cells
+Cells immediately before 년/월/일 (year/month/day) markers.
+
+### Heuristic 4: Image Fields
+Same logic as DOCX Heuristic 8, adapted for HWPX elements:
+- `<hp:pic>` instead of `<w:drawing>`
+- `<hp:tc>` / `<hp:t>` instead of `<w:tc>` / `<w:t>`
+- Same image keyword list and type classification
+
+### Heuristic 5: Tip Box
+An `<hp:tbl>` that:
+- Has `rowCnt="1"` and `colCnt="1"` (single-cell table)
+- `borderFillIDRef` resolves to DASH border style in `header.xml`
+- Cell text starts with `※` or contains `작성 팁` / `작성요령` / `작성 요령`
+- May appear standalone or nested inside a `<hp:subList>` within another cell
+
+→ `field_type: "tip_box"`, `action: "delete"`, `container: "standalone"|"nested"`
+
+### Heuristic 6: Section Header Rows
+Table rows where:
+- First cell spans multiple columns (`hp:cellSpan colSpan > 1`)
+- Text is short and descriptive (section name)
+- Background may be shaded
+
+## HWPX Pre-Fill Sanitization
+
+### Negative Character Spacing
+HWPX templates may define `<hh:charPr>` elements in `header.xml` with negative `<hh:spacing>` values (e.g., `hangul="-3"`). These compress characters closer together, which works for short placeholder text but causes **severe text overlap** when the filler replaces placeholders with longer content.
+
+**Rule**: Before filling, scan ALL `<hh:charPr>` definitions in `header.xml` and set any negative spacing attribute values to `"0"`. This applies to all attributes: `hangul`, `latin`, `hanja`, `japanese`, `other`, `symbol`, `user`.
+
+**Example fix**:
+```xml
+<!-- Before (causes overlap) -->
+<hh:spacing hangul="-3" latin="-3" hanja="-3" japanese="-3" other="-3" symbol="-3" user="-3"/>
+
+<!-- After (normal spacing) -->
+<hh:spacing hangul="0" latin="0" hanja="0" japanese="0" other="0" symbol="0" user="0"/>
+```
+
+## False Positive Filtering
+
+Exclude detected "fields" that are:
+- Part of a header/title row (not fillable)
+- Copyright notices or footer text
+- Page numbers or running headers
+- Table of contents entries
+- Cross-reference markers