fix+docs: pre-release review fixes (OOXML lvl ordering, stale docs, verb tables)

Multi-agent pre-release review of the v0.7.0..HEAD wave (4 dimensions, every
HIGH/MEDIUM finding adversarially verified): 10 confirmed, 7 fixed here, 3
correctly deferred to the release commit (plugin/marketplace version bumps and
the [Unreleased] -> 0.8.0 conversion).

- REAL BUG (docx numbering, D3 defensive path): creating a missing w:numFmt /
  w:lvlText on a cloned w:lvl used append(), which violates the ECMA-376 CT_Lvl
  child sequence when w:pPr/w:rPr already exist (Word rejects out-of-order
  children). Added _LVL_CHILD_ORDER + _insert_lvl_child_ordered (the
  established _insert_ppr_child_ordered pattern) and used it at both sites.
- Stale docs from the 6-axis evolution: common/appearance.py module +
  apply_role_appearance docstrings, formats/docx/typography.py module
  docstring, tests/test_typography.py module docstring now describe all six
  axes, their differing pathways and the E3 parity ledger.
- documentation/USAGE.md: the IntermediateDocument section now documents the
  cover named-slot shape ({"cover": {"title", "subtitle"}}) and the toc block -
  the exact authoring gap the e2e validation tripped over.
- skills/*/SKILL.md (all three, kept structurally aligned): "The seven verbs"
  table - the deterministic core plus comprehend / learn / propose-overrides /
  refine, each marked fail-closed and advisory-until-accept.

Gate: ruff clean; suite 848; anchor + reference-sync 17; real-render 70.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ferdinandobons

documentation/USAGE.md

@@ -23,8 +23,13 @@ the profile resolves all of that.
 
 ```json
 {
-  "cover": { "title": "Quarterly Review", "fields": { "doc_id": "RPT-001" } },
+  "cover": {
+    "title": "Quarterly Review",
+    "subtitle": "Q2 - Revenue and delivery",
+    "fields": { "doc_id": "RPT-001", "date": "2026-06-10" }
+  },
   "blocks": [
+    { "type": "toc", "title": "Contents", "max_level": 3 },
     { "type": "heading", "level": 1, "text": "Highlights" },
     { "type": "paragraph", "text": "This paragraph resolves to the brand body style." },
     { "type": "callout", "intent": "info", "text": "The profile chooses the callout style." },
@@ -34,6 +39,20 @@ the profile resolves all of that.
 }
 ```
 
+Structural notes:
+
+- The optional top-level **`cover`** object carries named semantic slots only:
+  `title`, an optional `subtitle`, and an optional `fields` mapping of
+  key-to-value pairs (document id, date, author, ...). The profile decides where
+  and how each slot renders on the template's own cover.
+- A **`toc`** block is a table-of-contents placeholder, not content: it carries an
+  optional `title` and a `max_level` (default 3), and the engine emits a native
+  field or defers to a preserved template outline.
+- Block order in `blocks` is the author's reading order; every block resolves
+  through semantic roles, so nothing in the JSON names a style, color or font.
+
+A comprehensive worked example lives at
+[`skills/brand-docx/examples/intermediate-document.example.json`](../skills/brand-docx/examples/intermediate-document.example.json).
 PowerPoint uses the same `IntermediateDocument`; Excel uses a `GridDocument`
 (named-region fills, formulas preserved).
 

scripts/brandkit/common/appearance.py

@@ -1,27 +1,40 @@
 # SPDX-License-Identifier: MIT
-"""Format-neutral brand APPEARANCE apply orchestration (font / size / color).
+"""Format-neutral brand APPEARANCE apply orchestration (font / size / color /
+geometry / table / numbering).
 
 This is the shared control flow the per-format generators (docx and pptx today;
-xlsx in a later PR) delegate to so the "read the three axes off the resolver op,
-then brand each run only when its axis is unset" logic has exactly ONE writer
-across kinds.
+xlsx in a later PR) delegate to so the "read the appearance axes off the resolver
+op, then brand each run/paragraph only when its axis is unset" logic has exactly
+ONE writer across kinds.
 
 It is lxml / python-docx / pptx / openpyxl-FREE at import (like
-:mod:`brandkit.common.text`): the per-axis run mutations and the set-only-when-unset
-probes live behind a small BACKEND object the format adapter supplies (e.g. docx's
-``DOCX_BACKEND`` wrapping ``run.font.name``/``.size``/``.color``; pptx's
-``PPTX_BACKEND``). This module only:
+:mod:`brandkit.common.text`): the per-axis run/paragraph mutations and the
+set-only-when-unset probes live behind a small BACKEND object the format adapter
+supplies (e.g. docx's ``DOCX_BACKEND`` wrapping ``run.font.name``/``.size``/
+``.color`` and the paragraph's ``w:pPr`` geometry; pptx's ``PPTX_BACKEND``). This
+module only:
 
   1. reads the captured brand axes off the resolver op (:func:`op_latin` /
-     :func:`op_size_hp` / :func:`op_color`) - STRICTLY from ``op.appearance``, never
-     a literal in the engine, so off-brand output stays impossible by construction;
+     :func:`op_size_hp` / :func:`op_color` / :func:`op_geometry` / :func:`op_table` /
+     :func:`op_numbering`) - STRICTLY from ``op.appearance``, never a literal in the
+     engine, so off-brand output stays impossible by construction. The axes ride
+     different pathways: font/size/color are run axes applied here through the
+     backend; geometry is a paragraph axis applied here via the backend's
+     ``set_geometry`` hook (docx-only today); table and numbering are docx-only and
+     realized by dedicated writers OUTSIDE this orchestration, but declared in
+     :data:`APPEARANCE_AXES` so the parity ledger measures them;
   2. resolves a run's ``color`` palette TOKEN to its captured ref
      (:func:`resolve_run_color`), recording a graceful INFO finding for an unknown
      token (the writer never fabricates a color);
-  3. drives the backend to apply those axes (:func:`apply_role_appearance` over a
-     paragraph's runs; :func:`apply_run_color` for a single run), gating each write
-     on the backend's ``*_unset`` probe so an inherited-but-correct value is never
-     clobbered and re-runs stay byte-identical.
+  3. drives the backend to apply the run/paragraph axes
+     (:func:`apply_role_appearance` over a paragraph's runs and geometry;
+     :func:`apply_run_color` for a single run), gating each write on the backend's
+     ``*_unset`` probe so an inherited-but-correct value is never clobbered and
+     re-runs stay byte-identical;
+  4. keeps the parity ledger (Cluster E3): :func:`_record_degraded_axes` emits one
+     INFO ``appearance_apply_degraded`` finding per captured axis the format backend
+     does not declare it realizes, so an unmaterialized axis surfaces gracefully
+     instead of silently dropping.
 
 The brand guarantee is preserved end to end: every applied value comes only from
 ``op.appearance`` / the resolved palette ref, the set-only-when-unset guard is
@@ -283,15 +296,19 @@ def resolve_run_color(
 def apply_role_appearance(
     backend: AppearanceBackend, target, op, findings: list[Finding]
 ) -> None:
-    """Apply captured brand typography (font, size, color) from the resolved op as
-    direct run formatting on ``target``'s runs (hyperlink runs included for docx).
+    """Apply captured brand typography (font, size, color) and geometry from the
+    resolved op as direct run/paragraph formatting on ``target`` (hyperlink runs
+    included for docx).
 
-    The three axes are INDEPENDENT: each is applied only when the run's corresponding
+    The run axes are INDEPENDENT: each is applied only when the run's corresponding
     ``*_unset`` probe is true, so a role carrying a size but no font (or a color but
-    no font) still applies the axes it has. A target that exposes no runs (a docx
-    table here) yields nothing and is skipped. An empty appearance (a pre-capture
-    profile) returns before touching any run, so output stays byte-identical to
-    today."""
+    no font) still applies the axes it has. Geometry is a separate PARAGRAPH-level
+    axis, applied per paragraph via the backend's ``set_geometry`` hook (its
+    set-only-when-unset guard lives per PROPERTY inside the backend). Table and
+    numbering are MEASURED here by the parity ledger but realized by dedicated
+    format-specific writers elsewhere. A target that exposes no runs (a docx table
+    here) yields nothing and is skipped. An empty appearance (a pre-capture profile)
+    returns before touching any run, so output stays byte-identical to today."""
     # Parity ledger (Cluster E3): surface any captured axis this backend cannot
     # realize BEFORE the early return, so a table/numbering-only op on a format
     # without those writers is still measured. Appends findings only; it never

scripts/brandkit/formats/docx/generate.py

@@ -1099,6 +1099,46 @@ def _ensure_numbering_def_present(doc, shell_doc, abstract_num_id: str) -> None:
         out_root.append(clone)
 
 
+# The WordprocessingML ``CT_Lvl`` child sequence (spec-fixed order, ECMA-376
+# ``w:lvl``). A re-asserted level fact must be inserted BEFORE the first existing
+# child that follows it in this order (e.g. ``w:lvlText`` precedes ``w:pPr``), or a
+# strict OOXML reader rejects the cloned definition. The peer of
+# :data:`_PPR_CHILD_ORDER` / :data:`_TBLPR_CHILD_ORDER` for the numbering part.
+_LVL_CHILD_ORDER: tuple[str, ...] = (
+    "w:start",
+    "w:numFmt",
+    "w:lvlRestart",
+    "w:pStyle",
+    "w:isLgl",
+    "w:suff",
+    "w:lvlText",
+    "w:lvlPicBulletId",
+    "w:legacy",
+    "w:lvlJc",
+    "w:pPr",
+    "w:rPr",
+)
+
+
+def _insert_lvl_child_ordered(lvl, tag: str):
+    """Get-or-create ``lvl/<tag>`` at the SPEC-CORRECT position in the ``CT_Lvl`` child
+    sequence (so Word accepts the cloned numbering definition). Returns the existing
+    element when present, else a new one inserted before the first existing successor
+    in :data:`_LVL_CHILD_ORDER` (appended only when no successor exists)."""
+    existing = lvl.find(qn(tag))
+    if existing is not None:
+        return existing
+    el = OxmlElement(tag)
+    successors = _LVL_CHILD_ORDER[_LVL_CHILD_ORDER.index(tag) + 1 :]
+    for child in lvl:
+        for succ in successors:
+            if child.tag == qn(succ):
+                child.addprevious(el)
+                return el
+    lvl.append(el)
+    return el
+
+
 def _reassert_level_facts(lvl, facts: dict) -> None:
     """Re-assert one level's captured facts (numFmt / lvlText / indent) onto its
     ``w:lvl`` element, SET-ONLY-WHEN-UNSET (Cluster D3).
@@ -1107,32 +1147,22 @@ def _reassert_level_facts(lvl, facts: dict) -> None:
     authored value (the shell's own, or a manual edit) is never clobbered and re-runs
     stay byte-identical. The engine writes only VALUES the profile captured from the
     shell (never synthesized): ``w:numFmt@w:val`` / ``w:lvlText@w:val`` are set on the
-    existing or a freshly-created child; each ``w:ind`` attribute is set on the level's
-    ``w:pPr/w:ind`` set-only-when-unset."""
+    existing or a freshly-created child (created at its SPEC-CORRECT ``CT_Lvl``
+    position via :func:`_insert_lvl_child_ordered`); each ``w:ind`` attribute is set
+    on the level's ``w:pPr/w:ind`` set-only-when-unset."""
     numfmt = facts.get("numFmt")
     if numfmt is not None:
-        el = lvl.find(qn("w:numFmt"))
-        if el is None:
-            el = OxmlElement("w:numFmt")
-            lvl.insert(0, el)
-            el.set(qn("w:val"), str(numfmt))
-        elif el.get(qn("w:val")) is None:
+        el = _insert_lvl_child_ordered(lvl, "w:numFmt")
+        if el.get(qn("w:val")) is None:
             el.set(qn("w:val"), str(numfmt))
     lvltext = facts.get("lvlText")
     if lvltext is not None:
-        el = lvl.find(qn("w:lvlText"))
-        if el is None:
-            el = OxmlElement("w:lvlText")
-            lvl.append(el)
-            el.set(qn("w:val"), str(lvltext))
-        elif el.get(qn("w:val")) is None:
+        el = _insert_lvl_child_ordered(lvl, "w:lvlText")
+        if el.get(qn("w:val")) is None:
             el.set(qn("w:val"), str(lvltext))
     indent = facts.get("indent") or {}
     if indent:
-        ppr = lvl.find(qn("w:pPr"))
-        if ppr is None:
-            ppr = OxmlElement("w:pPr")
-            lvl.append(ppr)
+        ppr = _insert_lvl_child_ordered(lvl, "w:pPr")
         ind = ppr.find(qn("w:ind"))
         if ind is None:
             ind = OxmlElement("w:ind")

scripts/brandkit/formats/docx/typography.py

@@ -1,32 +1,44 @@
 # SPDX-License-Identifier: MIT
-"""DOCX brand typography capture (font family, size, and color).
-
-The brand's REAL visible typography often lives as DIRECT run-level formatting
-(``w:rPr/w:rFonts`` / ``w:sz`` / ``w:color``) on the template's content rather than
-in the named styles or the theme: a designed template may put everything in
-``Normal`` with a direct Roboto / Montserrat override at 22 half-points in accent1.
-Role inference (``roles.py``) and theme extraction read only named styles and
-``theme1.xml``, so those direct values are never captured and a generated document
-falls back to the ``docDefaults`` font/size/color.
-
-This module captures the DOMINANT direct run typography, deterministically, as
-THREE INDEPENDENT axes (font family, size, color) sampled in a SINGLE pass:
-
-  - per role: the dominant explicit value among the runs that use the role's style
-    -> ``role['appearance']['font'] = {'latin': <name>}`` /
-    ``role['appearance']['size_hp'] = <int>`` /
-    ``role['appearance']['color'] = {'kind': ...}``;
-  - the document's effective body typography: the dominant explicit value across all
-    body runs -> ``theme['fonts']['body']['latin'/'size_hp']`` and
+"""DOCX brand appearance capture (run typography and structural appearance).
+
+The brand's REAL visible appearance often lives as DIRECT formatting on the
+template's content rather than in the named styles or the theme: a designed
+template may put everything in ``Normal`` with a direct Roboto / Montserrat
+override at 22 half-points in accent1, hand-tuned paragraph spacing, and an
+explicit ``w:tblLook`` on every table. Role inference (``roles.py``) and theme
+extraction read only named styles and ``theme1.xml``, so those direct values are
+never captured and a generated document falls back to the ``docDefaults``.
+
+This module captures the DOMINANT direct values, deterministically, as INDEPENDENT
+appearance axes:
+
+  - run typography (:func:`capture_fonts`, a SINGLE pass over the runs): font
+    family, size, and color, per role (the dominant explicit value among the runs
+    that use the role's style -> ``role['appearance']['font'] = {'latin': <name>}``
+    / ``role['appearance']['size_hp'] = <int>`` / ``role['appearance']['color'] =
+    {'kind': ...}``) and as the document's effective body typography
+    (``theme['fonts']['body']['latin'/'size_hp']`` and
     ``theme['text']['body']['color']`` - the fallbacks the generator applies to a
-    paragraph whose role carries no captured value.
+    paragraph whose role carries no captured value);
+  - paragraph GEOMETRY (:func:`capture_geometry`, Cluster D1, docx-only): the
+    dominant explicit ``w:pPr`` spacing / indentation / paragraph borders / shading,
+    per role (``role['appearance']['geometry']``) and as the body default
+    (``theme['geometry']['body']``);
+  - TABLE conditional-format facts (:func:`capture_table_appearance`, Cluster D2,
+    docx-only): the dominant explicit ``w:tblLook`` bitmask, referenced table-style
+    id, and ``w:tblCellMar`` margins, per ``table.*`` role
+    (``role['appearance']['table']``) and as ``theme['table']['body']``.
+
+(The sixth axis, list NUMBERING / Cluster D3, is captured in ``roles.py``, not
+here.)
 
 Each axis is independent: a role may carry a captured size but no captured font
 (or vice versa). Only a clear DOMINANT is recorded per axis (at least
-:data:`_MIN_RUNS` explicit values and a winner covering at least
-:data:`_MIN_DOMINANCE` of them), with its dominance stored as a per-axis confidence
-(``confidence`` for font, ``size_confidence`` for size, ``color_confidence`` for
-color). Capture is deterministic (model-free).
+:data:`~brandkit.common.typography.MIN_RUNS` explicit values and a winner covering
+at least :data:`~brandkit.common.typography.MIN_DOMINANCE` of them), with its
+dominance stored as a per-axis confidence (``confidence`` for font,
+``size_confidence`` for size, ``color_confidence`` for color). Capture is
+deterministic (model-free).
 
 The brand guarantee is preserved: every captured value is a FACT observed in the
 template, stored in the profile, applied only via the resolver, and re-validated

skills/brand-docx/SKILL.md

@@ -19,17 +19,23 @@ write JSON or run shell commands. The agent converts the user's content into an
 IntermediateDocument, invokes the internal engine, verifies the output, and
 returns the generated `.docx`.
 
-## The four verbs
+## The seven verbs: three deterministic + four model-assisted
 
 Every brand skill (`brand-docx`, `brand-pptx`, `brand-xlsx`) implements the same
-contract: **extract / comprehend / verify / generate**.
+contract. The deterministic core is **extract / verify / generate**; on top of it
+sit the optional learning verbs **comprehend / learn / propose-overrides /
+refine**, each fail-closed (the engine validates every proposal and authors every
+value).
 
 | Verb | Input | Output |
 |---|---|---|
 | **extract** | a company `.docx` template | a reusable Brand Profile |
 | **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block |
 | **verify** | a saved Brand Profile | QA findings + a verdict |
 | **generate** | content (an IntermediateDocument) + a profile | a new on-brand `.docx` |
+| **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` |
+| **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` |
+| **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |
 
 `comprehend` is **optional**: `generate` works on the deterministic profile alone.
 When a current comprehension is present, `generate` additionally reconciles the

skills/brand-pptx/SKILL.md

@@ -19,17 +19,23 @@ the deck they want; the agent converts that request into an IntermediateDocument
 uses the internal Python engine, verifies the output, and returns the generated
 `.pptx`.
 
-## The four verbs
+## The seven verbs: three deterministic + four model-assisted
 
 Every brand skill (`brand-docx`, `brand-pptx`, `brand-xlsx`) implements the same
-contract: **extract / comprehend / verify / generate**.
+contract. The deterministic core is **extract / verify / generate**; on top of it
+sit the optional learning verbs **comprehend / learn / propose-overrides /
+refine**, each fail-closed (the engine validates every proposal and authors every
+value).
 
 | Verb | Input | Output |
 |---|---|---|
 | **extract** | a company `.pptx` template | a reusable Brand Profile |
 | **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block |
 | **verify** | a saved Brand Profile | QA findings + a verdict |
 | **generate** | content (an IntermediateDocument) + a profile | a new on-brand `.pptx` |
+| **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` |
+| **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` |
+| **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |
 
 `comprehend` is **optional**: `generate` works on the deterministic profile alone.
 See [reference/comprehension.md](reference/comprehension.md) for the full step.