fix: harden OOXML boundaries and atomic generation

Author: ferdinandobons

.github/workflows/ci.yml

@@ -8,14 +8,14 @@ jobs:
   # Model-free lane: lint + typecheck (informational) + the full pytest suite.
   # External renderers (soffice/pdftoppm) are absent here, so the visual QA
   # tests degrade/skip exactly as on a developer machine without LibreOffice.
-  # The matrix enforces the supported-Python floor (pyproject requires-python
-  # ">=3.10"): the suite must pass on 3.10 (the floor), 3.11 and 3.12.
+  # The matrix enforces the complete supported range declared by pyproject:
+  # 3.10 (the floor), 3.11, 3.12 and 3.13.
   test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     env:
       FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
     steps:
@@ -24,14 +24,15 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
-          cache-dependency-path: requirements.txt
-      - run: python -m pip install -r requirements.txt pytest
-      # Lint gate: pinned to the version used locally so CI and dev agree. The
+          cache-dependency-path: |
+            requirements.txt
+            requirements-ci.txt
+      - run: python -m pip install -r requirements-ci.txt
+      # Lint gate: requirements-ci.txt pins the version used locally. The
       # tracked ruff.toml (defaults + line-length 88, target py310) is the source
       # of truth; both commands must be green before pytest runs.
       - name: Ruff lint
         run: |
-          python -m pip install ruff==0.15.2
           ruff check .
           ruff format --check .
       # Typecheck is informational only: the engine is lxml-Optional-heavy and
@@ -40,8 +41,7 @@ jobs:
       - name: Mypy (informational)
         continue-on-error: true
         run: |
-          python -m pip install mypy
-          mypy scripts/brandkit || true
+          mypy scripts/brandkit
       - name: Tests
         run: PYTHONPATH=scripts python -m pytest -q
 
@@ -61,7 +61,7 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
-      - run: python -m pip install -r requirements.txt pytest
+      - run: python -m pip install -r requirements-ci.txt
       - name: Install LibreOffice and poppler
         run: |
           sudo apt-get update

CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to BrandDocs are documented in this file.
 
+## [Unreleased]
+
+### Security
+
+- The live extract, generate, deterministic-QA and visual-render boundaries now
+  validate OOXML packages before third-party parsers see them. Archive size,
+  inflated part/package size, entry count, compression ratio, duplicate members,
+  unsafe paths and the required content-types part are enforced centrally, so the
+  existing decompression-bomb defense is no longer limited to an unused unpacker.
+
+### Fixed
+
+- XLSX generation now restores the template's x14 sparkline groups after the
+  openpyxl save, and the new fail-closed `extension_survival` L0 check detects any
+  worksheet extension family/count lost between shell and output.
+- `generate` validates schema/resolvers/provenance before authoring and writes to a
+  same-directory temporary file, publishing with an atomic replace only after QA
+  passes. Failed runs no longer overwrite an existing good output or print it as
+  generated.
+- Whole-row/whole-column Excel names are bounded to the worksheet's used rectangle;
+  discontiguous names fail with a clear error instead of being silently truncated;
+  XLSX text scans and demo clearing visit materialized cells only.
+- Fixture-builder import/build errors now fail CI instead of becoming skips, and
+  the example DOCX builder uses character-style names instead of deprecated
+  style-id lookup.
+
+### Changed
+
+- CI/dev dependencies are pinned in `requirements-ci.txt`, warnings are errors
+  except for the explicitly accounted-for openpyxl sparkline warning, and the
+  tested/supported Python range is now explicit at 3.10-3.13.
+
 ## [0.10.0] - 2026-06-10
 
 Hero-image polish release.

CONTRIBUTING.md

@@ -11,7 +11,7 @@ to keep that promise true while many hands touch the code.
 git clone https://github.com/ferdinandobons/brand-docs.git
 cd brand-docs
 python3 -m venv .venv && . .venv/bin/activate
-pip install -r requirements.txt pytest ruff
+pip install -r requirements-ci.txt
 ```
 
 Optional but recommended, the visual QA renderers (LibreOffice + Poppler,
@@ -30,7 +30,7 @@ Without them the engine still works; visual QA degrades to deterministic-only
 The suite has three lanes. The first is the one every PR must keep green:
 
 ```bash
-# 1) Full model-free suite (what CI runs on 3.10 / 3.11 / 3.12)
+# 1) Full model-free suite (what CI runs on 3.10 / 3.11 / 3.12 / 3.13)
 PYTHONPATH=scripts python -m pytest -q
 
 # 2) Real-render lane (needs LibreOffice + Poppler; CI runs it in its own job)

CONVENTIONS.md

@@ -378,6 +378,11 @@ saved profile's history). New ids follow `{entity}_{predicate}` in lowercase sna
 deviate from the pattern (e.g. `appearance_table_targets`, `schema`) are grandfathered,
 not a template to copy.
 
+`extension_survival` is a load-bearing XLSX structural diff: every worksheet
+extension URI/count present in the shell must survive generation. The generator
+restores self-contained sparkline extensions at the raw OOXML layer; an unsupported
+extension that cannot be preserved fails explicitly rather than disappearing.
+
 ---
 
 ## 10. Units

README.md

@@ -9,7 +9,7 @@
 **BrandDocs is a set of agent skills that learn your existing Word, PowerPoint and Excel templates and generate new on-brand documents from them.** Unlike generic AI document generators, it preserves **brand, structure, styles and formulas by construction**. Built for Claude Code, Codex and compatible AI agents.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-3B82F6.svg)](LICENSE)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
+[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-3776AB.svg)](https://www.python.org/)
 [![CI](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml)
 [![Website](https://img.shields.io/badge/website-GitHub%20Pages-16A34A.svg)](https://ferdinandobons.github.io/brand-docs/)
 [![Latest release](https://img.shields.io/github/v/release/ferdinandobons/brand-docs?label=latest%20release)](https://github.com/ferdinandobons/brand-docs/releases/latest)
@@ -54,13 +54,18 @@ All three share one engine and expose the same verbs: **`extract` → `comprehen
 
 **Two-phase by design:** the deterministic engine works with **no model at all** (extract / verify / generate, fully offline); the model-assisted verbs sit ON TOP and can only NAME captured facts - every proposal is validated fail-closed, so the brand guarantee never depends on a model being right.
 
+**Published only after proof:** generation preflights the profile and shell, writes
+to a same-directory temporary file, and atomically publishes the requested output
+only after deterministic QA passes. XLSX also preserves formulas and raw worksheet
+extensions such as sparkline groups; extension loss is a blocking QA error.
+
 ---
 
 ## Prerequisites
 
 BrandDocs runs locally and needs a few things installed **before first use**:
 
-- **Python ≥ 3.10** plus the packages in [`requirements.txt`](requirements.txt) (`python-docx`, `python-pptx`, `openpyxl`, `lxml`, `Pillow`):
+- **Python 3.10-3.13** plus the packages in [`requirements.txt`](requirements.txt) (`python-docx`, `python-pptx`, `openpyxl`, `lxml`, `Pillow`):
   ```bash
   pip install -r requirements.txt
   ```

SECURITY.md

@@ -7,8 +7,8 @@ BrandDocs is in **alpha** (`0.x`). Security fixes are applied to the latest
 
 | Version | Supported |
 |---------|-----------|
-| `0.1.x` | ✅        |
-| `< 0.1` | ❌        |
+| Latest `0.x` release | ✅        |
+| Older `0.x` releases | ❌        |
 
 ## Reporting a vulnerability
 
@@ -40,4 +40,8 @@ BrandDocs parses untrusted Office (OOXML) files. Areas of particular interest:
 
 The engine is self-contained (`python-docx` / `python-pptx` / `openpyxl` +
 `lxml`) with no cloud calls, which limits exposure, but template input is still
-untrusted and handled accordingly.
+untrusted and handled accordingly. Every live extract/generate/QA/render entrypoint
+validates the OOXML ZIP metadata before handing bytes to a third-party parser:
+compressed and inflated size ceilings, entry-count and per-part limits, duplicate
+parts, unsafe paths, compression ratio, and the required content-types part are
+checked centrally.

documentation/ARCHITECTURE.md

@@ -106,8 +106,8 @@ which were degraded, and what to repair next.
 
 | Layer | What it proves | What happens on failure |
 |---|---|---|
-| **Preflight** | `doctor` checks required Python packages, optional renderers (`soffice`, `pdftoppm`, PyMuPDF/`fitz`), and optional OCR (`tesseract`) before work starts. | Missing required packages must be installed/repaired. Missing visual/OCR tools downgrade only that proof layer. |
-| **L0 deterministic QA** | Schema validity, resolver targets, allowed styles/layouts/ranges, residual demo text, markdown leaks, structural diffs, formula preservation. | The gate fails or emits explicit findings before the output is treated as clean. |
+| **Preflight** | `doctor` checks dependencies; the shared OOXML boundary checks archive/part sizes, entry count, duplicate/unsafe paths and compression ratio before any Office parser or renderer opens a file. Generate also validates profile, resolver and shell provenance before authoring. | Missing dependencies must be repaired; unsafe packages and invalid/drifted profiles fail before an output is created. Missing visual/OCR tools downgrade only that proof layer. |
+| **L0 deterministic QA** | Schema validity, resolver targets, allowed styles/layouts/ranges, residual demo text, markdown leaks, structural diffs, formula preservation, and XLSX worksheet-extension survival. | The gate fails before the temporary output is atomically published; a failed run cannot replace a previous good deliverable. |
 | **L1 visual proxies** | Rendered-page signals such as blank pages, zero pages, content near page/slide edges, and optional OCR hits for visible residual template text. | Findings are warnings because the engine can detect symptoms, not intent. |
 | **L2 visual judgement** | The orchestrator opens the PNGs from `visual_manifest.json`, judges checklist items, and decides whether the result is visually acceptable. `strict` turns unclean visual evidence into gate errors. | Apply a targeted repair, regenerate, and rerun `--qa deep` or `--qa strict` until clean or honestly blocked. |
 

documentation/DEVELOPMENT.md

@@ -2,7 +2,7 @@
 
 ```bash
 python3 -m venv .venv && . .venv/bin/activate
-pip install -r requirements.txt pytest ruff
+pip install -r requirements-ci.txt
 PYTHONPATH=scripts pytest -q        # docx / pptx / xlsx / security / integration / smoke suites
 ```
 

documentation/INSTALLATION.md

@@ -17,7 +17,7 @@ skills to your agent.
 
 ### Required: core extract / generate / deterministic QA
 
-- **Python ≥ 3.10**: Python packages (from [`requirements.txt`](../requirements.txt)):
+- **Python 3.10-3.13**: Python packages (from [`requirements.txt`](../requirements.txt)):
   `python-docx>=1.1`, `python-pptx>=1.0`, `openpyxl>=3.1`, `lxml>=5.0`, `Pillow>=10.0`
 
 ```bash

documentation/PLUGIN_WORKFLOW.md

@@ -208,6 +208,7 @@ generated/<job>/
 | Native object loss | `component_survival` warning | ensure the native writer is used (charts, SmartArt, merged tables, docx TOC); explain only a genuinely unsupported object (e.g. a `divider` on pptx, which has no native form) |
 | XLSX range overflow | named range bounds error | split data, shrink input, or ask user to expand template range |
 | Formula loss | formula preservation finding | stop and repair generator; never ship silently |
+| XLSX extension loss | `extension_survival` error | restore the supported raw OOXML extension or reject the output; never ship a workbook with silently removed native objects |
 
 ## Round Budget Policy