python-hwpx 4.1.1__py3-none-any.whl → 4.2.0__py3-none-any.whl

hwpx/evalplan_fill.py

@@ -54,16 +54,64 @@ def _md_table_header(block: str) -> list[str]:
     return []
 
 
+@dataclass
+class RubricItem:
+    """One 평가요소 (evaluation element) with its observable-criteria 배점 ladder —
+    ``levels`` is ``[(descriptor, 배점), …]`` top score first, verbatim from the MD.
+    ``subtotal`` marks a 소계 row (the sub-area 만점, not a scored element)."""
+    name: str
+    levels: list[tuple[str, str]] = field(default_factory=list)
+    subtotal: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "levels": [list(l) for l in self.levels],
+                "subtotal": self.subtotal}
+
+
+@dataclass
+class RubricSubArea:
+    """A 세부 영역 (가./나. …) or, for a single-table area, one anonymous sub-area
+    (``label==""``). ``points`` is the 소계 (0 if the MD gives none)."""
+    label: str = ""
+    points: int = 0
+    items: list[RubricItem] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"label": self.label, "points": self.points,
+                "items": [it.to_dict() for it in self.items]}
+
+
 @dataclass
 class Rubric:
     title: str                       # "문제해결에 탐색 활용하기"
     points: int                      # 35
     standards: str                   # "[12인기02-04][12인기02-05]"
     rows: list[list[str]] = field(default_factory=list)   # [평가항목, 채점 기준]
+    # --- detailed 배점 rubric (current 평가계획 MD format), empty for the legacy
+    # synthetic format; :attr:`detailed` gates the detailed fill route.
+    subareas: list[RubricSubArea] = field(default_factory=list)
+    base_score: str = ""             # 기본점수 (백지·미참여)
+    long_score: str = ""             # 장기 미인정 결석자 (기본점수 −1)
+    task: str = ""                   # 수행과제
+    method: str = ""                 # 평가 방법
+    student_notes: str = ""          # 학생 유의사항
+    criteria: str = ""               # 평가기준(상/중/하) — 2015-개정 (3학년) only
+
+    @property
+    def detailed(self) -> bool:
+        """True when parsed from the current 평가계획 MD (per-element 배점 ladders)."""
+        return bool(self.subareas)
+
+    @property
+    def items(self) -> list[RubricItem]:
+        """All 평가요소 across sub-areas, in document order (flattened view)."""
+        return [it for sa in self.subareas for it in sa.items]
 
     def to_dict(self) -> dict[str, Any]:
         return {"title": self.title, "points": self.points,
-                "standards": self.standards, "rows": self.rows}
+                "standards": self.standards, "rows": self.rows,
+                "subareas": [sa.to_dict() for sa in self.subareas],
+                "base_score": self.base_score, "long_score": self.long_score}
 
 
 @dataclass
@@ -107,6 +155,59 @@ def _section(md: str, start_pat: str, end_pats: list[str]) -> str:
     return rest[:cut]
 
 
+# a per-standard header: ``**[code]** 진술`` at the start of a line
+_ACH_STD_HEADER = re.compile(r"^\s*\*\*\s*(\[[^\]\n]+\])\s*\*\*\s*(.*?)\s*$")
+
+
+def _parse_achievement_std(block: str) -> list[list[str]]:
+    """Parse §4가 into one row per 성취기준: ``[standard, L1_desc, L2_desc, ...]``.
+
+    Two markdown authoring shapes are accepted; the level count is read from the
+    data, never hard-coded:
+
+    * **unified** -- a single table ``성취기준 | 상 | 중 | 하`` (or ``| A |…| E |``) with
+      one row per standard, level descriptors across the columns. Parsed by
+      :func:`_md_table_rows`.
+    * **per-standard** -- a sequence of ``**[code]** 진술`` headers, each followed by
+      its own ``수준 | 성취수준`` table listing the levels as *rows*. Each is normalised
+      to ``[code+진술, <descriptor per level, in table order>]``, so a standard with an
+      A~E table becomes a 6-field row (bh = 5) matching the unified shape that
+      :func:`fill_achievement` and :func:`_std_level_map` already consume.
+
+    The per-standard shape is tried first; when no ``**[code]**`` header carries a
+    table, the unified single-table parse is returned instead."""
+    lines = block.splitlines()
+    n = len(lines)
+    stds: list[list[str]] = []
+    i = 0
+    while i < n:
+        m = _ACH_STD_HEADER.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        standard = f"{m.group(1)} {m.group(2)}".strip()
+        # advance to this standard's table (blank/prose lines may intervene), but
+        # stop at the next standard header -- a header with no table of its own.
+        j = i + 1
+        while j < n and not lines[j].lstrip().startswith("|"):
+            if _ACH_STD_HEADER.match(lines[j]):
+                break
+            j += 1
+        rows: list[list[str]] = []
+        while j < n and lines[j].lstrip().startswith("|"):
+            cells = [c.strip() for c in lines[j].strip().strip("|").split("|")]
+            if not all(set(c) <= {"-", ":", " "} and c for c in cells):
+                rows.append(cells)
+            j += 1
+        if len(rows) >= 2:                        # header row + >=1 level row
+            descs = [r[-1] for r in rows[1:]]     # right-most column = the descriptor
+            stds.append([standard, *descs])
+            i = j
+        else:
+            i += 1
+    return stds or _md_table_rows(block)
+
+
 def parse_review_md(md_text: str) -> EvalPlanContent:
     """Parse a 평가계획 review markdown into structured content."""
     c = EvalPlanContent()
@@ -134,7 +235,7 @@ def parse_review_md(md_text: str) -> EvalPlanContent:
     s4 = sec(4)
     ga = s4.split("**나.")[0]
     na = ("**나." + s4.split("**나.")[1]) if "**나." in s4 else ""
-    c.achievement_std = _md_table_rows(ga)
+    c.achievement_std = _parse_achievement_std(ga)
     c.levels = _md_table_rows(na)
 
     c.achieve_rate = _md_table_rows(sec(5))
@@ -166,6 +267,20 @@ def _prose(text: str) -> str:
 
 
 def _parse_rubrics(s7: str) -> list[Rubric]:
+    """Parse §7 수행평가 세부기준 into one :class:`Rubric` per 수행영역.
+
+    Dispatches on format: the current 평가계획 MD writes each area as an ``#### ①
+    title`` H4 heading with per-세부영역 ``평가요소 | 수행수준(채점 기준) | 배점`` tables
+    (the *detailed* 배점 rubric) — :func:`_parse_rubrics_detailed`. The older synthetic
+    format bolds the header inline (``**① title (NN점)**``) with a single flat 채점
+    기준(배점) table — :func:`_parse_rubrics_legacy`. Detection is structural (an H4
+    circled heading), never subject-specific."""
+    if re.search(r"(?m)^####\s*[" + _CIRCLED + r"]", s7):
+        return _parse_rubrics_detailed(s7)
+    return _parse_rubrics_legacy(s7)
+
+
+def _parse_rubrics_legacy(s7: str) -> list[Rubric]:
     rubrics: list[Rubric] = []
     # split on the bolded circled headers "**① title (NN점)** ..."
     parts = re.split(r"\*\*([" + _CIRCLED + r"][^*]*?\(\d+점\)[^*]*)\*\*", s7)
@@ -183,6 +298,158 @@ def _parse_rubrics(s7: str) -> list[Rubric]:
     return rubrics
 
 
+def _strip_inline_md(s: str) -> str:
+    """Drop ``**bold**`` / `` `code` `` emphasis, collapse whitespace — cell text is
+    spliced verbatim otherwise (no summarisation)."""
+    return _norm(re.sub(r"\*\*|`", "", s or ""))
+
+
+def _iter_md_tables(block: str):
+    """Yield ``(preamble, header_cells, data_rows)`` for every GitHub table in *block*
+    in order. ``preamble`` is the non-table text since the previous table — it carries
+    the ``［세부 영역 …］`` marker that names each sub-area."""
+    lines = block.splitlines()
+    i, preamble = 0, []
+    while i < len(lines):
+        if lines[i].strip().startswith("|"):
+            tbl = []
+            while i < len(lines) and lines[i].strip().startswith("|"):
+                tbl.append(lines[i].strip())
+                i += 1
+            rows = []
+            for t in tbl:
+                cells = [c.strip() for c in t.strip("|").split("|")]
+                if all(set(c) <= {"-", ":", " "} and c for c in cells):
+                    continue
+                rows.append(cells)
+            if rows:
+                yield "\n".join(preamble), rows[0], rows[1:]
+            preamble = []
+        else:
+            preamble.append(lines[i])
+            i += 1
+
+
+def _area_bullet(body: str, label: str) -> str:
+    """The value of a ``- **{label}**: …`` meta bullet in an area body ('' if absent)."""
+    m = re.search(rf"[-*]\s*\*\*{label}\*\*\s*[:：]?\s*(.+)", body)
+    return m.group(1).strip() if m else ""
+
+
+def _area_points(body: str, header: str) -> int:
+    """영역 만점 for an area — from the meta bullet / blockquote ('영역 만점: 50점',
+    '> 영역 만점 35점') or a ``(NN점)`` in the heading, else 0."""
+    m = re.search(r"영역\s*만점[은]?\**\s*[:：]?\s*(\d+)\s*점", body)
+    if not m:
+        m = re.search(r"\((\d+)\s*점\)", header)
+    return int(m.group(1)) if m else 0
+
+
+def _area_standards(body: str) -> str:
+    """The 성취기준 codes cited by an area, concatenated ('[12인기02-04][12인기02-05]')."""
+    m = re.search(r"(?:교육과정\s*성취기준|성취기준\s*/\s*성취수준|성취기준)[^\n]*?[:：]\s*(.+)", body)
+    src = m.group(1) if m else body
+    codes = re.findall(r"\[1\d[가-힣A-Za-z]*\d\d-\d\d\](?:\s*~\s*\[1\d[가-힣A-Za-z]*\d\d-\d\d\])?", src)
+    return "".join(codes)
+
+
+def _parse_area_rubric(header: str, title: str, body: str) -> Rubric:
+    """One 수행영역 → a detailed :class:`Rubric`: sub-area ``평가요소 | 수행수준 | 배점``
+    tables become :class:`RubricSubArea` blocks of :class:`RubricItem` ladders, and the
+    ［영역 공통］ / inline 기본점수 rows become ``base_score`` / ``long_score``. Content is
+    read verbatim — no invented 배점, no summarisation."""
+    rub = Rubric(title=title, points=_area_points(body, header),
+                 standards=_area_standards(body),
+                 task=_strip_inline_md(_area_bullet(body, "수행과제")),
+                 method=_strip_inline_md(_area_bullet(body, "평가 방법")),
+                 student_notes=_strip_inline_md(_area_bullet(body, "학생 유의사항")),
+                 criteria=_area_bullet(body, r"평가기준\(상/중/하\)"))
+    for pre, hdr, rows in _iter_md_tables(body):
+        hdr_txt = " ".join(hdr)
+        if "평가요소" in hdr_txt and "배점" in hdr_txt:
+            rub.subareas.append(_parse_subarea(pre, rows, rub))
+        elif "구분" in hdr_txt and "배점" in hdr_txt:
+            _absorb_base_row(rows, rub)          # ［영역 공통］ table
+    _sync_legacy_rows(rub)
+    return rub
+
+
+def _parse_subarea(preamble: str, rows: list[list[str]], rub: Rubric) -> RubricSubArea:
+    """Group a sub-area table's rows into 평가요소 items (new item = non-empty 평가요소
+    cell, continuation rows = extra levels). A named sub-area's 소계 row is kept as a
+    trailing subtotal item (verbatim md — it marks the 가/나 boundary and the sub-area
+    만점); 기본점수 / 장기 미인정 rows (appearing inline in single-table areas) feed
+    ``rub.base_score`` / ``long_score``."""
+    m = re.search(r"［세부 영역\s*([가-힣])\.\s*(.+?)\s*\((\d+)\s*점\)］", preamble or "")
+    sa = RubricSubArea(label=f"{m.group(1)}. {m.group(2)}" if m else "",
+                       points=int(m.group(3)) if m else 0)
+    cur: RubricItem | None = None
+    for row in rows:
+        c0 = _strip_inline_md(row[0]) if len(row) > 0 else ""
+        c1 = _strip_inline_md(row[1]) if len(row) > 1 else ""
+        c2 = _strip_inline_md(row[2]) if len(row) > 2 else ""
+        if "소계" in c0:
+            if c2.isdigit():
+                sa.points = int(c2)
+            if sa.label:                         # keep 소계 as a subtotal row (가/나 marker)
+                sm = re.match(r"(.*?소계)\s*\((.*)\)\s*$", c0)
+                name, note = (sm.group(1), sm.group(2)) if sm else (c0, "")
+                sa.items.append(RubricItem(name=name, levels=[(note, c2)], subtotal=True))
+            cur = None
+            continue
+        if "장기 미인정" in c0 or "장기미인정" in c0:
+            if c2.isdigit():
+                rub.long_score = c2
+            continue
+        if "기본점수" in c0:
+            if c2.isdigit():
+                rub.base_score = c2
+            continue
+        if c0:                                   # a new 평가요소
+            cur = RubricItem(name=c0)
+            sa.items.append(cur)
+        if cur is not None and (c1 or c2):
+            cur.levels.append((c1, c2))
+    return sa
+
+
+def _absorb_base_row(rows: list[list[str]], rub: Rubric) -> None:
+    """Read ［영역 공통］ ``구분 | 배점`` rows into ``base_score`` / ``long_score``. 장기
+    미인정 rows also carry '기본점수' (—1점), so match the more specific label first."""
+    for row in rows:
+        c0 = _strip_inline_md(row[0]) if row else ""
+        cN = _strip_inline_md(row[-1]) if row else ""
+        if not cN.isdigit():
+            continue
+        if "장기 미인정" in c0 or "장기미인정" in c0:
+            rub.long_score = cN
+        elif "기본점수" in c0:
+            rub.base_score = cN
+
+
+def _sync_legacy_rows(rub: Rubric) -> None:
+    """Mirror the detailed model into the legacy ``rows`` shape ([name, 'desc **s** / …']
+    + a trailing 기본점수 summary) so legacy introspection / scorers keep working."""
+    rows: list[list[str]] = []
+    for it in rub.items:
+        ladder = " / ".join(f"{d} **{s}**" if s else d for d, s in it.levels)
+        rows.append([it.name, ladder])
+    if rub.base_score or rub.long_score:
+        rows.append([f"기본점수 **{rub.base_score}** · 장기 미인정 결석 **{rub.long_score}**", ""])
+    rub.rows = rows
+
+
+def _parse_rubrics_detailed(s7: str) -> list[Rubric]:
+    """Parse the current-format §7 (``#### ①`` areas) into detailed rubrics."""
+    heads = list(re.finditer(r"(?m)^####\s*([" + _CIRCLED + r"])\s*(.+?)\s*$", s7))
+    out: list[Rubric] = []
+    for k, m in enumerate(heads):
+        start = m.end()
+        end = heads[k + 1].start() if k + 1 < len(heads) else len(s7)
+        out.append(_parse_area_rubric(m.group(0), m.group(2).strip(), s7[start:end]))
+    return out
+
+
 def _norm(text: str) -> str:
     return " ".join(text.split()).strip()
 
@@ -262,11 +529,17 @@ def plan_structural_ops(blank: str | Path, content: EvalPlanContent | None = Non
     # rubric example (연주/비평 for 3학년, 6 국어 영역 for 2학년); the content needs
     # `exp[kind]` of them. Delete the extras (keep the first) so the structure
     # matches the content-derived skeleton.
+    detailed_rubrics = bool(content and content.rubrics and content.rubrics[0].detailed)
     if exp:
         for kind in ("achievement", "level", "rubric"):
             idxs = by_kind.get(kind, [])
             want = exp.get(kind, 0)
-            for i in idxs[want:]:
+            # For detailed rubrics the blank ships filled donor samples FIRST (인권·인포
+            # 그래픽) and clean empty templates LAST; the leading 인권 sample carries an
+            # extra 세부 항목 column the MD never uses, so keep the trailing clean
+            # templates instead (drop the surplus from the front).
+            surplus = idxs[:len(idxs) - want] if (kind == "rubric" and detailed_rubrics) else idxs[want:]
+            for i in surplus:
                 if i not in del_tables:
                     del_tables.append(i)
                     transcript.append(f"delete_table #{i} (surplus {kind} example) — "
@@ -1162,6 +1435,488 @@ def _fill_rubric_headings(data: bytes, content: EvalPlanContent) -> tuple[bytes,
     return pres.data, skipped
 
 
+# --------------------------------------------------------------------------- #
+# Detailed §7 fill (current 평가계획 MD) -- per-평가요소 배점 ladders. Reshapes the
+# blank rubric's 평가요소 ladder to the MD's element count (grow / shrink the col0
+# vertical-merge blocks) and splices every observable criterion + 배점 verbatim.
+# Every target is located by geometry (label text / grid spans), reusable across the
+# form family, and every edit goes through the byte-preserving table_patch primitives.
+# --------------------------------------------------------------------------- #
+
+def _row_label_value(grid: Any, rep: Any, tb: bytes, matches) -> tuple[int | None, Any, Any]:
+    """(row, label_cell, value_cell) for the first cell whose text satisfies *matches*;
+    value_cell is the grid cell immediately to its right (spanning-aware)."""
+    from .table_patch import _text_of
+    for r in range(rep.row_count):
+        for c in range(rep.col_count):
+            cell = grid.get((r, c))
+            if cell is None or cell.row != r or cell.col != c:
+                continue
+            if matches(_text_of(tb[cell.start:cell.end])):
+                return r, cell, grid.get((r, c + cell.col_span))
+    return None, None, None
+
+
+def _fill_2022_header(data: bytes, ti: int, rub: Rubric) -> tuple[bytes, list[str]]:
+    """Overwrite the header value cells (평가 영역명 / 영역 만점 / 학기 / 수행과제 / 학생
+    유의사항) — located by their label, so it works on both the clean template and the
+    donor samples that survive structural pruning."""
+    from .table_patch import fill_cells
+    _sp, tb, grid, rep = _grid_of(data, ti)
+
+    def _n(t: str) -> str:
+        return t.replace(" ", "").strip()
+
+    specs = [
+        (lambda t: _n(t) == "평가영역명", rub.title, 3),
+        (lambda t: _n(t) == "영역만점", f"{rub.points}점", 1),
+        (lambda t: _n(t) == "학기", "2학기", 1),
+        (lambda t: _n(t) == "수행과제", rub.task, 6),
+        (lambda t: _n(t) == "학생유의사항", rub.student_notes, 6),
+    ]
+    cells: list[dict[str, Any]] = []
+    for pred, val, ml in specs:
+        if not val:
+            continue
+        _r, _lc, vc = _row_label_value(grid, rep, tb, pred)
+        if vc is not None:
+            cells.append({"table_index": ti, "row": vc.row, "col": vc.col, "text": val, "max_lines": ml})
+    # 평가 방법: the donor sample's checkbox grid carries the WRONG subject's ☑ marks.
+    # Overwrite the value cell with the MD's method (its ☑ list) and blank the second
+    # checkbox row so no foreign check survives.
+    if rub.method:
+        mr, _mlc, mvc = _row_label_value(grid, rep, tb, lambda t: _n(t) == "평가방법")
+        if mvc is not None:
+            cells.append({"table_index": ti, "row": mvc.row, "col": mvc.col, "text": rub.method, "max_lines": 2})
+            nxt = grid.get((mvc.row + 1, mvc.col))
+            if nxt is not None and nxt.row == mvc.row + 1:
+                cells.append({"table_index": ti, "row": nxt.row, "col": nxt.col, "text": "", "max_lines": 1})
+    fr = fill_cells(data, cells)
+    return fr.data, [s.reason for s in fr.skipped]
+
+
+def _delete_2022_ae_block(data: bytes, ti: int) -> tuple[bytes, list[str]]:
+    """Delete the 성취기준 + 성취기준별 성취수준 (A~E) block. The current MD gives no
+    per-area A~E descriptors (it refers to §4), so keeping the sample rows would show
+    empty/foreign A~E — dropping them is the honest render. Bounds: the '성취기준' label
+    row through the row before '평가 방법'."""
+    from .table_patch import apply_table_ops, _text_of
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    ae_start = method_row = None
+    for r in range(rep.row_count):
+        c0 = grid.get((r, 0))
+        if c0 is None or c0.row != r:
+            continue
+        t = _text_of(tb[c0.start:c0.end]).replace(" ", "").strip()
+        if ae_start is None and t == "성취기준":
+            ae_start = r
+        if t == "평가방법":
+            method_row = r
+            break
+    if ae_start is None or method_row is None or method_row <= ae_start:
+        return data, [f"rubric ti={ti}: A~E block bounds not found (성취기준={ae_start}, 평가방법={method_row})"]
+    rows = list(range(ae_start, method_row))
+    res = apply_table_ops(data, [{"op": "delete_row", "table_index": ti, "rows": sorted(rows, reverse=True)}])
+    if not res.ok:
+        return data, [f"rubric ti={ti}: delete A~E block: {[s.reason for s in res.skipped]}"]
+    return res.data, []
+
+
+def _grow_ladder_groups(data: bytes, ti: int, n: int) -> tuple[bytes, list[str]]:
+    """Reshape the col0 평가요소 ladder to exactly *n* groups. Clones the shortest clean
+    group block (``insert_block_by_clone`` — copies formatting byte-for-byte) to grow,
+    deletes whole surplus blocks to shrink. Fail-closed."""
+    from .table_patch import apply_table_ops
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    ph, base = _pf_bounds(tb, grid, rep)
+    if ph is None or base is None:
+        return data, [f"rubric ti={ti}: no 평가요소/기본점수 bounds for ladder growth"]
+    groups = _pf_groups(tb, ph, base)
+    g = len(groups)
+    if g == n:
+        return data, []
+    if g < n:
+        r0, h = min(groups, key=lambda gh: gh[1])       # clone the shortest block
+        res = apply_table_ops(data, [{"op": "insert_block_by_clone", "table_index": ti,
+                                      "ref_rows": [r0, r0 + h - 1], "count": n - g}])
+        if not res.ok:
+            return data, [f"rubric ti={ti}: grow ladder to {n} groups: {[s.reason for s in res.skipped]}"]
+        return res.data, []
+    del_rows: list[int] = []
+    for r0, h in groups[n:]:
+        del_rows.extend(range(r0, r0 + h))
+    res = apply_table_ops(data, [{"op": "delete_row", "table_index": ti,
+                                  "rows": sorted(set(del_rows), reverse=True)}])
+    if not res.ok:
+        return data, [f"rubric ti={ti}: shrink ladder to {n} groups: {[s.reason for s in res.skipped]}"]
+    return res.data, []
+
+
+def _fill_2022_ladder_detailed(data: bytes, ti: int, items: list[RubricItem]) -> tuple[bytes, bool, list[str]]:
+    """Normalize each 평가요소 group to its element's level count and splice the
+    descriptor + 배점 of every level (verbatim from the MD's structured levels — never
+    the lossy '/'-joined form). ``_grow_ladder_groups`` must have made the group count
+    equal to ``len(items)`` first. Reuses the byte-preserving group reshape helpers."""
+    from .table_patch import fill_cells
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    ph, base = _pf_bounds(tb, grid, rep)
+    if ph is None or base is None:
+        return data, False, [f"rubric ti={ti}: no ladder bounds"]
+    bat_col = rep.col_count - 1
+    desc_col = _pf_desc_col(tb, ph, base, bat_col)
+    has_sub = desc_col > 1
+    groups = _pf_groups(tb, ph, base)
+    if len(groups) != len(items):
+        return data, False, [f"rubric ti={ti}: {len(groups)} 평가요소 groups != {len(items)} MD elements"]
+
+    d = data
+    for gi in range(len(groups) - 1, -1, -1):
+        m = max(1, len(items[gi].levels))
+        _sp, tb, grid, rep = _grid_of(d, ti)
+        ph2, base2 = _pf_bounds(tb, grid, rep)
+        r0, h = _pf_groups(tb, ph2, base2)[gi]
+        if has_sub:
+            d, _fh, sub_sk = _reduce_to_first_subitem(d, ti, r0, h)
+            if sub_sk:
+                return data, False, [f"rubric ti={ti} group {gi}: {sub_sk[0]}"]
+            _sp, tb, grid, rep = _grid_of(d, ti)
+            ph2, base2 = _pf_bounds(tb, grid, rep)
+            r0, h = _pf_groups(tb, ph2, base2)[gi]
+        d, norm_sk = _normalize_ladder_group(d, ti, r0, h, m, desc_col, bat_col)
+        if norm_sk:
+            return data, False, [f"rubric ti={ti} group {gi}: {norm_sk[0]}"]
+
+    _sp, tb, grid, rep = _grid_of(d, ti)
+    ph2, base2 = _pf_bounds(tb, grid, rep)
+    gg = _pf_groups(tb, ph2, base2)
+    cells: list[dict[str, Any]] = []
+    for gi, (r0, _h) in enumerate(gg):
+        lead = grid.get((r0, 0))
+        if lead is not None:
+            cells.append({"table_index": ti, "row": lead.row, "col": lead.col,
+                          "text": items[gi].name, "max_lines": 4})
+        for k, (desc, score) in enumerate(items[gi].levels):
+            r = r0 + k
+            dc = grid.get((r, desc_col))
+            if dc is not None:
+                cells.append({"table_index": ti, "row": dc.row, "col": dc.col, "text": desc, "max_lines": 6})
+            bc = grid.get((r, bat_col))
+            if bc is not None and score:
+                cells.append({"table_index": ti, "row": bc.row, "col": bc.col, "text": score, "max_lines": 1})
+        if has_sub:
+            sc = grid.get((r0, 1))
+            if sc is not None and sc.col == 1:
+                cells.append({"table_index": ti, "row": sc.row, "col": 1, "text": "", "max_lines": 1})
+    fr = fill_cells(d, cells)
+    return fr.data, True, [s.reason for s in fr.skipped]
+
+
+def _fill_2022_base_scores(data: bytes, ti: int, rub: Rubric) -> tuple[bytes, list[str]]:
+    """Fill the 기본점수 / 장기 미인정 결석자 배점 cells (right-most column). The row
+    labels already carry the form's standard text, so only the 배점 is spliced. 장기
+    미인정 rows also contain '기본점수' (−1점), so match the more specific label first."""
+    from .table_patch import fill_cells, _text_of
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    bat_col = rep.col_count - 1
+    base_row = long_row = None
+    for r in range(rep.row_count):
+        c0 = grid.get((r, 0))
+        if c0 is None or c0.row != r:
+            continue
+        t = _text_of(tb[c0.start:c0.end])
+        if "장기 미인정" in t or "장기미인정" in t:
+            long_row = r
+        elif "기본점수" in t:
+            base_row = r
+    cells: list[dict[str, Any]] = []
+    for row, score in ((base_row, rub.base_score), (long_row, rub.long_score)):
+        if row is None or not score:
+            continue
+        bc = grid.get((row, bat_col))
+        if bc is not None:
+            cells.append({"table_index": ti, "row": bc.row, "col": bc.col, "text": score, "max_lines": 1})
+    fr = fill_cells(data, cells)
+    return fr.data, [s.reason for s in fr.skipped]
+
+
+def _fill_rubric_detailed_2022(data: bytes, ti: int, rub: Rubric) -> tuple[bytes, bool, list[str]]:
+    """Fill ONE 2022-개정 (평가 영역명) rubric with a detailed area's content: header
+    values, drop the A~E block, grow the 평가요소 ladder to the element count, splice
+    every level's criterion + 배점, and the 기본점수 배점. Returns (data, ladder_filled,
+    notes)."""
+    notes: list[str] = []
+    data, n = _fill_2022_header(data, ti, rub); notes += n
+    data, n = _delete_2022_ae_block(data, ti); notes += n
+    items = rub.items
+    data, n = _grow_ladder_groups(data, ti, len(items)); notes += n
+    data, filled, n = _fill_2022_ladder_detailed(data, ti, items); notes += n
+    data, n = _fill_2022_base_scores(data, ti, rub); notes += n
+    data = _prune_header_empty_bullets(data, ti)
+    return data, filled, notes
+
+
+def _split_criteria(criteria: str) -> tuple[str, str, str]:
+    """Split a 평가기준(상/중/하) bullet ('상=… ／ 중=… ／ 하=…') into its three
+    descriptors (verbatim, '' for any absent level)."""
+    out = {}
+    for key in ("상", "중", "하"):
+        m = re.search(rf"{key}\s*=\s*(.+?)(?=\s*[／/]\s*[상중하]\s*=|$)", criteria or "")
+        out[key] = _strip_inline_md(m.group(1)) if m else ""
+    return out["상"], out["중"], out["하"]
+
+
+def _3hak_ladder_bounds(tb: bytes, grid: Any, rep: Any) -> tuple[int | None, int | None]:
+    """(영역(만점) header row, 기본점수 row) of a 2015-개정 rubric ladder."""
+    from .table_patch import _text_of
+    hr = br = None
+    for r in range(rep.row_count):
+        c0 = grid.get((r, 0))
+        if c0 is not None and c0.row == r:
+            t = _text_of(tb[c0.start:c0.end]).replace(" ", "")
+            if "영역" in t and "만점" in t:
+                hr = r
+        c1 = grid.get((r, 1))
+        if c1 is not None and c1.row == r and br is None and "기본점수" in _text_of(tb[c1.start:c1.end]):
+            br = r
+    return hr, br
+
+
+def _fill_3hak_header(data: bytes, ti: int, rub: Rubric) -> tuple[bytes, list[str]]:
+    """Fill the 교육과정성취기준 codes, the 평가기준 상/중/하 descriptors, and 학생 유의
+    사항 — located by label geometry."""
+    from .table_patch import fill_cells
+
+    def _n(t: str) -> str:
+        return t.replace(" ", "").strip()
+
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    sang, jung, ha = _split_criteria(rub.criteria)
+    specs = [
+        (lambda t: _n(t) in ("교육과정성취기준", "성취기준"), rub.standards, 3),
+        (lambda t: _n(t) == "상", sang, 4),
+        (lambda t: _n(t) == "중", jung, 4),
+        (lambda t: _n(t) == "하", ha, 4),
+        (lambda t: _n(t) == "학생유의사항", rub.student_notes, 4),
+    ]
+    cells: list[dict[str, Any]] = []
+    for pred, val, ml in specs:
+        if not val:
+            continue
+        _r, _lc, vc = _row_label_value(grid, rep, tb, pred)
+        if vc is not None:
+            cells.append({"table_index": ti, "row": vc.row, "col": vc.col, "text": val, "max_lines": ml})
+    fr = fill_cells(data, cells)
+    return fr.data, [s.reason for s in fr.skipped]
+
+
+def _fill_3hak_base_scores(data: bytes, ti: int, rub: Rubric) -> tuple[bytes, list[str]]:
+    from .table_patch import fill_cells, _text_of
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    bat_col = rep.col_count - 1
+    base_row = long_row = None
+    for r in range(rep.row_count):
+        c1 = grid.get((r, 1))
+        if c1 is None or c1.row != r:
+            continue
+        t = _text_of(tb[c1.start:c1.end])
+        if "장기 미인정" in t or "장기미인정" in t:
+            long_row = r
+        elif "기본점수" in t:
+            base_row = r
+    cells: list[dict[str, Any]] = []
+    for row, score in ((base_row, rub.base_score), (long_row, rub.long_score)):
+        if row is None or not score:
+            continue
+        bc = grid.get((row, bat_col))
+        if bc is not None:
+            cells.append({"table_index": ti, "row": bc.row, "col": bc.col, "text": score, "max_lines": 1})
+    fr = fill_cells(data, cells)
+    return fr.data, [s.reason for s in fr.skipped]
+
+
+def _build_3hak_ladder(data: bytes, ti: int, rub: Rubric) -> tuple[bytes, bool, list[str]]:
+    """Reshape the 5-column 영역(만점)|평가항목|평가요소|채점 기준|배점 ladder to one physical
+    row per MD level, then subdivide the single 평가요소 merge into per-element blocks and
+    the 평가항목 merge into per-세부영역 blocks (``split_cell_vertical``, byte-preserving).
+    Leaders land on each block's top row; 채점 기준 + 배점 land on every level row."""
+    from .table_patch import apply_table_ops
+
+    subareas = [(sa.label, sa.points, [it for it in sa.items if not it.subtotal])
+                for sa in rub.subareas]
+    subareas = [(lbl, pts, its) for lbl, pts, its in subareas if its]
+    if not subareas:
+        return data, False, [f"rubric ti={ti}: 3학년 rubric has no scored elements"]
+
+    flat: list[tuple[str, str]] = []
+    item_sizes: list[int] = []
+    subarea_sizes: list[int] = []
+    item_leaders: list[tuple[int, str]] = []
+    subarea_leaders: list[tuple[int, str]] = []
+    off = 0
+    for lbl, pts, its in subareas:
+        sa_start, sa_total = off, 0
+        for it in its:
+            levels = it.levels or [("", "")]
+            item_leaders.append((off, it.name))
+            item_sizes.append(len(levels))
+            flat.extend(levels)
+            off += len(levels)
+            sa_total += len(levels)
+        subarea_leaders.append((sa_start, f"{lbl} ({pts}점)" if lbl else ""))
+        subarea_sizes.append(sa_total)
+    n = off
+
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    hr, br = _3hak_ladder_bounds(tb, grid, rep)
+    if hr is None or br is None:
+        return data, False, [f"rubric ti={ti}: no 영역(만점)/기본점수 ladder bounds"]
+    body0 = hr + 1
+    cur = br - body0
+    # Grow / shrink the body to n rows. Clone a COVERED body row (body0+1): its cells are
+    # rowSpan==1 (채점 기준·배점) while col0/1/2 merges span across it and auto-extend.
+    if n > cur:
+        res = apply_table_ops(data, [{"op": "insert_row_by_clone", "table_index": ti,
+                                      "ref_row": body0 + 1, "count": n - cur}])
+        if not res.ok:
+            return data, False, [f"rubric ti={ti}: grow ladder to {n} rows: {[s.reason for s in res.skipped]}"]
+        data = res.data
+    elif n < cur:
+        res = apply_table_ops(data, [{"op": "delete_row", "table_index": ti,
+                                      "rows": list(range(body0 + n, br))}])
+        if not res.ok:
+            return data, False, [f"rubric ti={ti}: shrink ladder to {n} rows: {[s.reason for s in res.skipped]}"]
+        data = res.data
+
+    # Subdivide 평가요소 (col2) per element and 평가항목 (col1) per 세부영역.
+    for col, sizes in ((2, item_sizes), (1, subarea_sizes)):
+        if len(sizes) > 1:
+            res = apply_table_ops(data, [{"op": "split_cell_vertical", "table_index": ti,
+                                          "row": body0, "col": col, "sizes": sizes}])
+            if not res.ok:
+                return data, False, [f"rubric ti={ti}: split col{col} {sizes}: {[s.reason for s in res.skipped]}"]
+            data = res.data
+
+    from .table_patch import fill_cells
+    _sp, tb, grid, rep = _grid_of(data, ti)
+    hr, _br = _3hak_ladder_bounds(tb, grid, rep)
+    body0 = hr + 1
+    bat_col = rep.col_count - 1
+    cells: list[dict[str, Any]] = []
+    c0 = grid.get((body0, 0))
+    if c0 is not None:
+        cells.append({"table_index": ti, "row": c0.row, "col": 0,
+                      "text": f"{rub.title}({rub.points}점)", "max_lines": 4})
+    for roff, lbl in subarea_leaders:
+        c = grid.get((body0 + roff, 1))
+        if c is not None and lbl:
+            cells.append({"table_index": ti, "row": c.row, "col": 1, "text": lbl, "max_lines": 4})
+    for roff, name in item_leaders:
+        c = grid.get((body0 + roff, 2))
+        if c is not None:
+            cells.append({"table_index": ti, "row": c.row, "col": 2, "text": name, "max_lines": 4})
+    for k, (desc, score) in enumerate(flat):
+        c3 = grid.get((body0 + k, 3))
+        if c3 is not None:
+            cells.append({"table_index": ti, "row": c3.row, "col": c3.col, "text": desc, "max_lines": 6})
+        c4 = grid.get((body0 + k, bat_col))
+        if c4 is not None and score:
+            cells.append({"table_index": ti, "row": c4.row, "col": c4.col, "text": score, "max_lines": 1})
+    fr = fill_cells(data, cells)
+    return fr.data, True, [s.reason for s in fr.skipped]
+
+
+def _fill_rubric_detailed_3hak(
+    data: bytes, ti: int, rub: Rubric, content: EvalPlanContent
+) -> tuple[bytes, bool, list[str]]:
+    """Fill ONE 2015-개정 (교육과정성취기준) rubric with a detailed area's content: header
+    (성취기준 / 평가기준 상·중·하 / 학생 유의사항), the nested 배점 ladder, and the 기본점수
+    배점. Returns (data, ladder_filled, notes)."""
+    notes: list[str] = []
+    data, n = _fill_3hak_header(data, ti, rub); notes += n
+    data, ok, n = _build_3hak_ladder(data, ti, rub); notes += n
+    data, n = _fill_3hak_base_scores(data, ti, rub); notes += n
+    data = _prune_header_empty_bullets(data, ti)
+    return data, ok, notes
+
+
+def _empty_trailing_para_spans(cell_xml: bytes) -> list[tuple[int, int]]:
+    """Byte spans of every empty ``<hp:p>`` after the first in a cell — the donor
+    template's leftover list-bullet paragraphs, which render as stray/red bullets once
+    the MD text is spliced into the first paragraph. The first paragraph is always
+    kept (a cell needs one)."""
+    s = cell_xml.decode("utf-8")
+    spans: list[tuple[int, int]] = []
+    for i, m in enumerate(re.finditer(r"<hp:p\b.*?</hp:p>", s, re.S)):
+        if i == 0:
+            continue
+        txt = "".join(re.findall(r"<hp:t\b[^>]*>(.*?)</hp:t>", m.group(0), re.S))
+        if not txt.strip():
+            spans.append((len(s[:m.start()].encode("utf-8")), len(s[:m.end()].encode("utf-8"))))
+    return spans
+
+
+def _prune_header_empty_bullets(data: bytes, ti: int) -> bytes:
+    """Drop the empty trailing bullet paragraphs left in a rubric's 수행과제 / 학생 유의
+    사항 value cells (byte-preserving: removes whole empty ``<hp:p>`` elements, rewrites
+    only the affected section part)."""
+    from .table_patch import _sections, _iter_table_spans, build_grid, _text_of
+    from .patch import _rewrite_zip_entries
+
+    idx = ti
+    for sp, section in sorted(_sections(data).items()):
+        spans = _iter_table_spans(section)
+        if idx >= len(spans):
+            idx -= len(spans)
+            continue
+        ts, te = spans[idx]
+        tb = section[ts:te]
+        grid, rep = build_grid(tb)
+        edits: list[tuple[int, int]] = []
+        for r in range(rep.row_count):
+            for cprime in range(rep.col_count):
+                cell = grid.get((r, cprime))
+                if cell is None or (cell.row, cell.col) != (r, cprime):
+                    continue
+                if _text_of(tb[cell.start:cell.end]).replace(" ", "").strip() not in ("수행과제", "학생유의사항"):
+                    continue
+                vc = grid.get((r, cell.col + cell.col_span))
+                if vc is None:
+                    continue
+                for a, b in _empty_trailing_para_spans(tb[vc.start:vc.end]):
+                    edits.append((ts + vc.start + a, ts + vc.start + b))
+        if not edits:
+            return data
+        new_section = section
+        for a, b in sorted(edits, reverse=True):
+            new_section = new_section[:a] + new_section[b:]
+        return _rewrite_zip_entries(data, {sp: new_section})
+    return data
+
+
+def _fill_rubrics_detailed(
+    data: bytes, content: EvalPlanContent, report: dict[str, Any]
+) -> tuple[bytes, dict[str, Any]]:
+    """Fill every §7 rubric from a detailed area. Routes by blank shape: 평가 영역명
+    tables (2학년) → :func:`_fill_rubric_detailed_2022`; 교육과정성취기준 tables (3학년) →
+    :func:`_fill_rubric_detailed_3hak`."""
+    filled = 0
+    for i, rub in enumerate(content.rubrics):
+        idxs = _rubric_indices(data)
+        if i >= len(idxs):
+            report["skipped"].append(f"rubric {i}: no matching blank table")
+            continue
+        ti = idxs[i]
+        if _rubric_is_2022(data, ti):
+            data, ok, notes = _fill_rubric_detailed_2022(data, ti, rub)
+        else:
+            data, ok, notes = _fill_rubric_detailed_3hak(data, ti, rub, content)
+        report["skipped"].extend(f"rubric {i}: {n}" for n in notes)
+        if ok:
+            filled += 1
+    report["filled"] = filled
+    return data, report
+
+
 def fill_rubrics(data: bytes, content: EvalPlanContent) -> tuple[bytes, dict[str, Any]]:
     """Fill each 수행평가 세부기준 rubric table from the matching review rubric
     (byte-preserving). Replaces the sample 성취기준 codes / 평가항목 labels.
@@ -1175,6 +1930,12 @@ def fill_rubrics(data: bytes, content: EvalPlanContent) -> tuple[bytes, dict[str
 
     report: dict[str, Any] = {"rubrics": len(content.rubrics), "filled": 0, "skipped": []}
 
+    # Detailed route (current 평가계획 MD): each area carries a per-element 배점 ladder
+    # that the summary routes below can't represent. Grows the blank's 평가요소 ladder to
+    # the MD's element count and splices every observable criterion + 배점 verbatim.
+    if content.rubrics and content.rubrics[0].detailed:
+        return _fill_rubrics_detailed(data, content, report)
+
     # 2022-개정 route: fill each rubric table's label cells + 채점기준 ladder + heading.
     idxs0 = _rubric_indices(data)
     if idxs0 and _rubric_is_2022(data, idxs0[0]):
@@ -1480,20 +2241,53 @@ def fill_sections(data: bytes, content: EvalPlanContent) -> tuple[bytes, dict[st
     return pres.data, report
 
 
+def _flatten_schedule_merges(data: bytes, ti: int) -> tuple[bytes, list[str]]:
+    """Split every vertical merge in the schedule's *data* rows into unit rows.
+
+    The donor ships a subject sample whose 단원명/성취기준 may span two weeks (a
+    ``rowSpan==2`` cell). The review has distinct content per week, so a naive
+    one-row-per-week fill writes the first week into the merged cell and can only
+    *skip* the second (its cell is covered) -- the second week's 단원/성취기준 is
+    absorbed. Splitting each vertical merge into unit cells (byte-preserving, the
+    original formatting cloned onto the new cell) restores the 1:1 mapping so no
+    row is absorbed. Header row (0) is left untouched. Content-agnostic."""
+    from .table_patch import apply_table_ops, _direct_cells
+    notes: list[str] = []
+    while True:
+        _sp, tb, _grid, _rep = _grid_of(data, ti)
+        merge = next(((c.row, c.col, c.row_span)
+                      for c in sorted(_direct_cells(tb), key=lambda c: (c.row, c.col))
+                      if c.row >= 1 and c.row_span > 1), None)
+        if merge is None:
+            break
+        r, col, rs = merge
+        res = apply_table_ops(data, [{"op": "split_cell_vertical", "table_index": ti,
+                                      "row": r, "col": col, "sizes": [1] * rs}])
+        if not res.ok:
+            notes.append(f"split donor merge r{r}c{col} (rowSpan {rs}) refused: "
+                         f"{[s.reason for s in res.skipped]}")
+            break
+        data = res.data
+        notes.append(f"split donor merge r{r}c{col} (rowSpan {rs}) into {rs} unit rows")
+    return data, notes
+
+
 def fill_schedule(data: bytes, content: EvalPlanContent) -> tuple[bytes, dict[str, Any]]:
     """Fill the Ⅰ 교수학습 운영 계획 schedule table from ``content.schedule`` (one
     logical row per review row, 6 columns), shrink-to-fit at 4 lines. Located by
-    the widest multi-row data table under the Ⅰ heading. Merged-cell skips (the
-    month/week span carry-overs) are expected and reported, not errors."""
+    the widest multi-row data table under the Ⅰ heading. Any vertical merge a donor
+    sample left in the data rows is split first so every review row maps to its own
+    form row (no absorption)."""
     from .table_patch import fill_cells
 
-    report: dict[str, Any] = {"rows": len(content.schedule), "filled": 0, "skipped": []}
+    report: dict[str, Any] = {"rows": len(content.schedule), "filled": 0, "skipped": [], "unmerged": []}
     if not content.schedule:
         return data, report
     ti = _schedule_index(data)
     if ti is None:
         report["skipped"].append("no schedule table found")
         return data, report
+    data, report["unmerged"] = _flatten_schedule_merges(data, ti)
     cells = []
     for i, row in enumerate(content.schedule):
         r = i + 1  # row 0 is the header
@@ -1708,6 +2502,171 @@ def fill_ratio(data: bytes, content: EvalPlanContent) -> tuple[bytes, dict[str,
     return fr.data, report
 
 
+def finalize_evalplan(data: bytes, content: EvalPlanContent) -> tuple[bytes, dict[str, Any]]:
+    """Deterministic post-fill cleanup: turn a *filled* donor 평가계획 form into a
+    submittable 채움본 without a bespoke driver script.
+
+    Runs the recipe's mechanical steps -- fill the title / teacher / 정의적 cells,
+    prune the donor's instruction scaffolding and orphaned sample headings (bounded
+    by the form's OWN section headings, never by subject or grade), strip the red
+    guidance runs, recolor filled blue slots to body black, and remove trailing
+    table captions. Every decision is structure/pattern based; no subject or grade
+    string appears. Genuine ambiguity (novel instruction phrasing, non-1:1 정의적
+    cell mapping, tie-broken 변형 선택) is intentionally NOT resolved here -- that is
+    the skill's (LLM) judgment.
+
+    ``data`` must already be a :func:`fill_evalplan` (``phase="all"``) output; the
+    deletes are computed while the red guidance runs are still intact so a black
+    ordinal sharing a paragraph with a red instruction is removed as a unit. Returns
+    ``(clean_bytes, report)``."""
+    import html
+    import io
+    import zipfile
+
+    from .body_patch import (
+        apply_body_ops,
+        direct_paragraph_spans,
+        recolor_runs_by_color,
+        strip_runs_by_color,
+    )
+    from .formfill_quality import _tables
+    from .guidance_scan import is_form_instruction
+    from .table_patch import fill_cells, strip_trailing_table_captions
+
+    T = re.compile(r"<hp:t(?:\s[^>]*)?>(.*?)</hp:t>", re.S)
+    RUN = re.compile(r"<hp:run\b[^>]*?>.*?</hp:run>", re.S)
+    ORDINAL = re.compile(r"^[가-하]\.?$|^\(\d+\)$|^\*+$|^[·・\s]*$")
+    # legit 평가계획 notes that sit among instructions -- form-generic, never a
+    # subject/grade token, so keeping them is not hardcoding a subject.
+    KEEP = ("가급적 동점자",)
+
+    report: dict[str, Any] = {
+        "deleted": 0, "skipped": [], "captions": 0,
+        "title": False, "teacher": False, "affective_rows": 0,
+    }
+
+    def _sec_hdr(d: bytes) -> tuple[str, str]:
+        z = zipfile.ZipFile(io.BytesIO(d))
+        sec = z.read("Contents/section0.xml").decode("utf-8")
+        hdr_name = next(n for n in z.namelist() if n.endswith("header.xml"))
+        return sec, z.read(hdr_name).decode("utf-8")
+
+    def _red_ids(hdr: str) -> set[str]:
+        out: set[str] = set()
+        for cm in re.finditer(
+            r"<hh:charPr\b[^>]*\bid=\"(\d+)\"[^>]*textColor=\"([#0-9A-Fa-f]+)\"", hdr
+        ):
+            if cm.group(2).upper() == "#FF0000":
+                out.add(cm.group(1))
+        return out
+
+    def _run_texts(block: str, reds: set[str]) -> tuple[str, str]:
+        black, red = [], []
+        for rm in RUN.finditer(block):
+            run = rm.group(0)
+            txt = html.unescape("".join(T.findall(run)))
+            cid = re.search(r'charPrIDRef="(\d+)"', run)
+            (red if (cid and cid.group(1) in reds) else black).append(txt)
+        return "".join(black), "".join(red)
+
+    # ---- paragraph deletes computed on the FILLED bytes (red still intact) ------
+    sec, hdr = _sec_hdr(data)
+    reds = _red_ids(hdr)
+    spans = direct_paragraph_spans(sec)
+    blocks = [sec[a:b] for (a, b) in spans]
+    texts = [html.unescape("".join(T.findall(bl))).strip() for bl in blocks]
+    has_tbl = ["<hp:tbl" in bl for bl in blocks]
+    del_idx: set[int] = set()
+
+    def first(pred, start: int = 0) -> int | None:
+        return next((i for i in range(start, len(texts)) if pred(i)), None)
+
+    # (2e) 성취수준별 고정분할점수 labels -- red form scaffolding; delete all (the
+    # engine already kept the single subject-matching 성취율 table by band count).
+    del_idx.update(
+        i for i in range(len(texts))
+        if not has_tbl[i] and texts[i].startswith("성취수준별 고정분할점수")
+    )
+
+    # (2a) 최소 성취수준 orphan heading block -- its table was pruned (공통과목 전용);
+    # delete the non-table paragraphs from the heading down to the §5 table.
+    ms = first(lambda i: not has_tbl[i] and texts[i].startswith("다. 최소 성취수준"))
+    sec5 = first(lambda i: has_tbl[i] and "기준 성취율과 성취도" in texts[i])
+    if ms is not None and sec5 is not None:
+        del_idx.update(i for i in range(ms, sec5) if not has_tbl[i])
+
+    # (2f) foreign donor sample headings between the §7 and §8 tables.
+    s7 = first(lambda i: has_tbl[i] and "수행평가 세부기준" in texts[i])
+    s8 = first(lambda i: has_tbl[i] and "정의적 능력 평가" in texts[i],
+               start=(s7 + 1) if s7 is not None else 0)
+    if s7 is not None and s8 is not None:
+        del_idx.update(i for i in range(s7 + 1, s8) if not has_tbl[i] and texts[i])
+
+    # (2b) foreign "(N) area" sub-headers between §4 and §5 (donor sample labels;
+    # the MD's §4 uses 가./나. markers, never "(N) word", so this is safe).
+    s4h = first(lambda i: has_tbl[i] and "성취기준 및 성취수준" in texts[i])
+    s5h = first(lambda i: has_tbl[i] and "기준 성취율과 성취도" in texts[i],
+                start=(s4h + 1) if s4h is not None else 0)
+    if s4h is not None and s5h is not None:
+        del_idx.update(
+            i for i in range(s4h + 1, s5h)
+            if not has_tbl[i] and re.match(r"^\(\d+\)\s*\S", texts[i])
+        )
+
+    # (2c) red-guidance-with-trivial-black + black instruction paragraphs.
+    for i, bl in enumerate(blocks):
+        if has_tbl[i] or i in del_idx or any(k in texts[i] for k in KEEP):
+            continue
+        black_txt, red_txt = _run_texts(bl, reds)
+        if red_txt.strip() and ORDINAL.match(black_txt.strip()):
+            del_idx.add(i)
+        elif is_form_instruction(texts[i]):
+            del_idx.add(i)
+
+    # ---- title + §8 정의적 + teacher fills (paragraph count unchanged) -----------
+    cells: list[dict[str, Any]] = []
+    if content.title:
+        cells.append({"table_index": 0, "row": 0, "col": 0, "text": content.title})
+        report["title"] = True
+    # §8 정의적 능력 평가 표: replace the donor sample with the MD's 측면 rows (1:1).
+    aff = re.findall(
+        r"(\S+적 측면\([^)]*\))\s*[:：]\s*(.+?)(?=\s*-\s*\S+적 측면|$)", content.affective or ""
+    )
+    aff_ti = next((gi for gi, t in enumerate(_tables(data)) if "정의적 능력 평가 요소" in t.text), None)
+    if aff_ti is not None and aff:
+        for r, (label, desc) in enumerate(aff[:3], start=1):
+            cells.append({"table_index": aff_ti, "row": r, "col": 0, "text": label.strip(), "max_lines": 3})
+            cells.append({"table_index": aff_ti, "row": r, "col": 1, "text": desc.strip(), "max_lines": 4})
+        report["affective_rows"] = min(len(aff), 3)
+    if cells:
+        data = fill_cells(data, cells).data
+    if content.teacher:
+        # fill the placeholder, then recolor the filled value to body-black so the
+        # red-strip below does not remove it; robust to the label+placeholder being
+        # in one run (2학년) or split black label + red placeholder (3학년).
+        data = apply_body_ops(data, [
+            {"op": "replace_text", "find": "◯◯◯, ◯◯◯", "replace": content.teacher, "count": 1},
+            {"op": "restyle_text", "find": content.teacher, "textColor": "#000000", "count": 1},
+            {"op": "replace_text", "find": "(**)", "replace": "", "count": 4},
+        ]).data
+        report["teacher"] = True
+
+    # ---- apply deletes (high->low so indices stay valid) ------------------------
+    dr = apply_body_ops(data, [{"op": "delete_paragraph", "index": i}
+                               for i in sorted(del_idx, reverse=True)])
+    data = dr.data
+    report["deleted"] = len(del_idx) - len(dr.skipped)
+    report["skipped"] = [str(s) for s in dr.skipped]
+
+    # ---- strip residual red, recolor filled blue->black, strip captions --------
+    data = strip_runs_by_color(data, ["#FF0000"]).data
+    data = recolor_runs_by_color(data, ["#0000FF"], "#000000").data
+    cap = strip_trailing_table_captions(data)
+    data = cap.data
+    report["captions"] = len(cap.applied)
+    return data, report
+
+
 def fill_evalplan(
     blank: str | Path,
     content: EvalPlanContent,
@@ -1721,8 +2680,12 @@ def fill_evalplan(
     정기시험 column, surplus example tables). ``phase="all"`` additionally runs the
     content fills -- schedule, achievement, levels, rubrics, section prose -- each
     byte-preserving and located by classification/geometry (index-safe against the
-    prior structural deletes). Returns the apply result dict plus the op-plan
-    transcript and, for ``phase="all"``, a ``content_report`` per region."""
+    prior structural deletes). ``phase="clean"`` runs ``"all"`` and then
+    :func:`finalize_evalplan` -- the deterministic post-fill cleanup (title/teacher/
+    정의적 fills, scaffolding + orphan prune, red-strip, blue->black recolor, caption
+    strip) that yields a submittable 채움본 with no bespoke driver. Returns the apply
+    result dict plus the op-plan transcript and, for ``phase`` in ``{"all","clean"}``,
+    a ``content_report`` per region (plus ``content_report["finalize"]`` for clean)."""
     from .table_patch import apply_table_ops
 
     plan = plan_structural_ops(blank, content)
@@ -1731,13 +2694,15 @@ def fill_evalplan(
     payload = result.to_dict()
 
     content_report: dict[str, Any] = {}
-    if phase == "all":
+    if phase in ("all", "clean"):
         data, content_report["schedule"] = fill_schedule(data, content)
         data, content_report["achievement"] = fill_achievement(data, content)
         data, content_report["levels"] = fill_levels(data, content)
         data, content_report["rubrics"] = fill_rubrics(data, content)
         data, content_report["ratio"] = fill_ratio(data, content)
         data, content_report["sections"] = fill_sections(data, content)
+    if phase == "clean":
+        data, content_report["finalize"] = finalize_evalplan(data, content)
 
     if output is not None:
         from pathlib import Path as _P
@@ -1756,7 +2721,7 @@ def parse_review_file(path: str | Path) -> EvalPlanContent:
 
 __all__ = [
     "EvalPlanContent", "Rubric", "parse_review_md", "parse_review_file",
-    "expected_skeleton", "plan_structural_ops", "fill_evalplan",
+    "expected_skeleton", "plan_structural_ops", "fill_evalplan", "finalize_evalplan",
     "fill_schedule", "fill_achievement", "fill_levels", "fill_rubrics", "fill_ratio",
     "fill_sections",
 ]

hwpx/guidance_scan.py

@@ -31,6 +31,7 @@ __all__ = [
     "Candidate",
     "GuidanceReport",
     "scan_form_guidance",
+    "is_form_instruction",
 ]
 
 # 도형 순회는 markdown_export와 동일 정책: rect/ellipse/polygon만.
@@ -49,6 +50,31 @@ _GUIDANCE_KEYWORD = re.compile(
 )
 _CONDITIONAL_CHOICE = re.compile(r"중에서.{0,20}(만\s*남기|남기고|선택)|해당하는\s*것만\s*남기")
 
+# 검정(무색) 안내 문단까지 걸러내는 확장 렉시콘. _GUIDANCE_KEYWORD는 색 후보
+# 스캔용이라 "교과별로 수정"·색 범례 문장 등 검정 지시문을 놓친다. 아래는 한국어
+# 양식의 작성-안내 상투 문구(과목/학년 비의존)로, 색이 아니라 텍스트로만 지시문을
+# 판정해야 하는 문단(빨강 지시는 색 strip이 처리)에 쓴다.
+# 검정(무색) 안내 문단 판정용 지시-문구 렉시콘. "유의)"·"※" 같은 *모호한* 마커는
+# 정상 유의사항 본문에도 쓰이므로 일부러 제외한다(over-삭제 방지) — 색으로 표시된
+# 지시는 body_patch.strip_runs_by_color가 별도로 지운다.
+_FORM_INSTRUCTION = re.compile(
+    r"삭제\s*바랍니다|삭제합니다|삭제!!|문의\s*주세요|"
+    r"작성해\s*주세요|작성해주세요|수정해\s*주세요|수정해주세요|맞추어\s*작성|"
+    r"교과별로\s*수정|교과별\s*특성이\s*드러나게|재구성하여\s*작성|이하는\s*작성|"
+    r"해당하는\s*것만\s*남기|추정분할점수|"
+    r"(검정|검은|빨간|빨강|파란|파랑)\s*(색\s*)?글씨|(빨간|파란)\s*글자"
+)
+
+
+def is_form_instruction(text: str) -> bool:
+    """양식 작성-안내 문단(삭제 지시·색 범례·"교과별로 수정" 등)인지 판정한다.
+
+    과목/학년 비의존 — 한국어 양식 지시 상투 문구 렉시콘 기반이다. 색 정보 없이
+    텍스트만으로 지시문을 걸러야 하는 검정 안내 문단용이며, 색으로 표시된 지시는
+    ``body_patch.strip_runs_by_color``가 별도로 처리한다. 렉시콘 밖의 *신규* 지시
+    표현은 이 예/아니오로 잡히지 않는다 — 그 판단은 스킬(LLM)의 몫이다."""
+    return bool(_FORM_INSTRUCTION.search(text or ""))
+
 # ── 색 범례 ────────────────────────────────────────────────────────
 _LEGEND_HINT = re.compile(r"글씨|글자")
 _COLOR_WORDS: dict[str, str] = {

hwpx/table_patch.py

@@ -1760,8 +1760,87 @@ def table_summary(source: str | Path | bytes) -> list[dict[str, Any]]:
     return out
 
 
+# --- trailing table-caption strip --------------------------------------------
+#
+# A donor 평가계획 form can bake a short "(N) <area>" sample caption as TRAILING
+# text of the same paragraph that wraps a table -- it sits between ``</hp:tbl>``
+# and that paragraph's ``<hp:linesegarray>``, so it is NOT a section-direct
+# paragraph that ``delete_paragraph`` can address. This removes only that caption
+# text (a ``(N) word`` group), closes the run cleanly right after the table, and
+# round-trips every other byte identical. Pattern-based, subject/grade agnostic.
+
+_TC_T = re.compile(r"<(?:[A-Za-z_][\w.-]*:)?t\b[^>]*>(.*?)</(?:[A-Za-z_][\w.-]*:)?t>", re.S)
+_TC_AFTER_TBL = re.compile(
+    r"</(?:[A-Za-z_][\w.-]*:)?tbl>(.*?)(?=<(?:[A-Za-z_][\w.-]*:)?linesegarray)", re.S
+)
+_TC_CAPTION = re.compile(r"\(\d+\)\s*\S{1,8}")
+
+
+def strip_trailing_table_captions(
+    source: str | Path | bytes, *, output_path: str | Path | None = None
+) -> CellFillResult:
+    """Strip short ``(N) <word>`` captions baked as trailing text of a table's
+    wrapper paragraph (between ``</hp:tbl>`` and its ``<hp:linesegarray>``).
+
+    Byte-preserving on every untouched part; namespace-prefix tolerant. Returns a
+    :class:`CellFillResult` whose ``applied`` records each stripped caption. Only a
+    parenthesised-ordinal + short word is removed; anything crossing a paragraph or
+    table boundary is left intact (fail-closed)."""
+    import html
+
+    source_bytes = _read_source_bytes(source)
+    import io
+    import zipfile
+
+    with zipfile.ZipFile(io.BytesIO(source_bytes), "r") as archive:
+        section_names = [
+            info.filename for info in archive.infolist()
+            if not info.is_dir() and re.search(r"section\d+\.xml$", info.filename)
+        ]
+        sections = {name: archive.read(name).decode("utf-8") for name in section_names}
+
+    applied: list[CellApplied] = []
+    changed_parts: dict[str, bytes] = {}
+    for name, sec in sections.items():
+        hits: list[str] = []
+
+        def _strip(m: "re.Match[str]") -> str:
+            stuff = m.group(1)
+            # never cross a paragraph or table boundary
+            if "</hp:p>" in stuff or "<hp:p" in stuff or "tbl>" in stuff or "<hp:tbl" in stuff:
+                return m.group(0)
+            txt = html.unescape("".join(_TC_T.findall(stuff))).strip()
+            if re.fullmatch(_TC_CAPTION, txt):
+                hits.append(txt)
+                # drop the caption text + trailing runs; close the table's run cleanly
+                return "</hp:tbl></hp:run>"
+            return m.group(0)
+
+        new = _TC_AFTER_TBL.sub(_strip, sec)
+        if new != sec:
+            changed_parts[name] = new.encode("utf-8")
+            for txt in hits:
+                applied.append(CellApplied(name, -1, -1, -1, txt, ""))
+
+    if not changed_parts:
+        open_safety, _ = _finalize(source_bytes, output_path, source=source)
+        return CellFillResult(source_bytes, (), (), (), True, "none", open_safety)
+    try:
+        output = _patch_zip_entries(source_bytes, changed_parts)
+        zip_method = "partial-local-record-copy"
+    except ValueError:
+        output = _rewrite_zip_entries(source_bytes, changed_parts)
+        zip_method = "zipfile-rewrite-fallback"
+    open_safety, _ = _finalize(output, output_path, source=source)
+    return CellFillResult(
+        output, tuple(applied), (), tuple(changed_parts), output == source_bytes,
+        zip_method, open_safety,
+    )
+
+
 __all__ = [
     "fill_cells", "build_grid", "GridReport", "CellFillResult", "CellApplied", "CellSkipped",
     "ResolvedCellTarget", "resolve_cell_target",
     "apply_table_ops", "TableStructureError", "verify_fill", "RenderCheckRequired", "table_summary",
+    "strip_trailing_table_captions",
 ]

{python_hwpx-4.1.1.dist-info → python_hwpx-4.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 4.1.1
+Version: 4.2.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -54,6 +54,7 @@ Dynamic: license-file
   </p>
   <p align="center">
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pepy.tech/project/python-hwpx"><img src="https://static.pepy.tech/badge/python-hwpx/month" alt="Downloads"></a>
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
     <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
     <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>

{python_hwpx-4.1.1.dist-info → python_hwpx-4.2.0.dist-info}/RECORD

@@ -3,17 +3,17 @@ hwpx/authoring.py,sha256=BoWGNc50ALMSuyjFUGl1iMCLYb1rFllCKVcuugvsaOw,129001
 hwpx/body_patch.py,sha256=yB3X0L3Jns38CpRFOvjvPMnovJ5a2SoVefh6FIy3uYQ,25736
 hwpx/document.py,sha256=_a0snPKzdsdIL9AmzvQzvOloqXB0CVq89vx6GjnKeHw,59186
 hwpx/errors.py,sha256=BgWhEFHiiiz9DoCNRwovHt95dz8HVzQx1C29PGfXMwQ,2619
-hwpx/evalplan_fill.py,sha256=UmXj6uo63Bo1iBI9lB3_e2G-z8dT_8nQBywwvfrepfM,83578
+hwpx/evalplan_fill.py,sha256=Nar0q2lkoCjNVHDaBegMywp1N1MrSGRMMd0UJgSp61I,130443
 hwpx/experimental.py,sha256=H8fBrmGf0BzoDS6dqwBpUChUestUgOpO7XjMEBXsssg,1499
 hwpx/fill_residue.py,sha256=Uq4DbwFNlbHrO3FQA7Yyk1I0gAsvPw6O8mPD82rmBws,8286
 hwpx/form_fill.py,sha256=VUIU53Qa9Ho2aP72biDvJwnDW7ngdAzu3PSd5A7d1JM,9908
 hwpx/formfill_quality.py,sha256=pRxZYb1cg95F2O78va5glMJ3UqPh1rewJB1Qz-LOlsc,38521
-hwpx/guidance_scan.py,sha256=62ltZsuaebWaDxDaMbbq870J5PQVZoz0ZCSZ39otBkE,25193
+hwpx/guidance_scan.py,sha256=EJXQlNKbHTHeqVeWQXSqryWJ-kzWMkHivOLUyZVxG5g,27039
 hwpx/mutation_report.py,sha256=6hurhDdgGiONeLIeWZJT8lwLtWJZ1VHp1l6G0zy0mQo,19409
 hwpx/package.py,sha256=0rKjGCJbPQvrVBIy07Jpjsu3fI7HhbqFCGWTiTDsJpo,1141
 hwpx/patch.py,sha256=6MEVGAjpaWKK7Oyxydfvk52-VzSJfHi6I-eUCGJHZQM,24846
 hwpx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hwpx/table_patch.py,sha256=R5DBCgImIU8e53nq9X3wqGPJlZ7pbZoiretgU2E__a8,78805
+hwpx/table_patch.py,sha256=Eu4mhZAzftYQpQyA3VFwDn9CSYChUDMvW3JQdb2Tobk,82297
 hwpx/template_formfit.py,sha256=dlxf98FatT5Nl4hN15TuMXqj5NlDTGSnLaqXVo_PoBo,23424
 hwpx/templates.py,sha256=28bYqeJVeDb1Cq8G9NZG9Mhnu4K2GamAKC4QhxvUZyA,1187
 hwpx/_document/__init__.py,sha256=gJ7N5W4EANv_341NJCtbxSh0QrNIBtArRAnjJUe_PE4,98
@@ -209,10 +209,10 @@ hwpx/visual/page_qa.py,sha256=AuJCySfLIdXjPeekhAc3YnrIWOsN0sI35Pnz8BZ6Pro,7278
 hwpx/visual/qa_contracts.py,sha256=1cjoiRTAWgi7NgE8SPc6bKxdoUfKx9nyou1mgC47TxY,10506
 hwpx/visual/qa_metrics.py,sha256=I7RdybN-f1Fvcv2j-ceDPoek51nOkMui1Zrd7TEX_C8,9838
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-4.1.1.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-4.1.1.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
-python_hwpx-4.1.1.dist-info/METADATA,sha256=5R5nvsB-mwhZxnwU0KQG3wXscXzEBa6TjdvA4iknZhg,9164
-python_hwpx-4.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-4.1.1.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
-python_hwpx-4.1.1.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-4.1.1.dist-info/RECORD,,
+python_hwpx-4.2.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-4.2.0.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
+python_hwpx-4.2.0.dist-info/METADATA,sha256=4xqn4MBxGvoHlqV6nSSPo30Yg0cg-5Yn2k0qWRvZdK0,9297
+python_hwpx-4.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-4.2.0.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
+python_hwpx-4.2.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-4.2.0.dist-info/RECORD,,