release: prepare DocMergeForge 2.8.5 candidate

.github/workflows/project-sync-safety.yml

@@ -41,10 +41,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip

.github/workflows/quality.yml

@@ -29,11 +29,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libegl1
       - run: python -m pip install --upgrade pip
-      - run: pip install -e ".[dev,web]"
+      - run: python -m pip install -e ".[dev,web]"
       - run: pre-commit validate-config
       - run: ruff check .
       - run: black --check --diff .
       - run: mypy src/docmergeforge
       - run: python scripts/check_docs_links.py
       - run: python scripts/check_repository_reference.py
-      - run: pytest --cov=docmergeforge --cov-report=term-missing
+      - run: python -m pytest --cov=docmergeforge --cov-report=term-missing

.github/workflows/regression.yml

@@ -28,7 +28,7 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libegl1
       - run: python -m pip install --upgrade pip
-      - run: pip install -e ".[dev]"
+      - run: python -m pip install -e ".[dev,web]"
       - run: python scripts/generate_120_fixture.py fixtures/generated/sql-120
-      - run: pytest -m "regression or integration" tests/regression tests/integration
+      - run: python -m pytest -m "regression or integration" tests/regression tests/integration
       - run: docmergeforge validate --input fixtures/generated/sql-120 --parts 1-120

docs/release-process.md

@@ -1,8 +1,8 @@
 # Release Process
 
-This document defines the evidence required to move DocMergeForge from a development checkpoint to a release candidate and, eventually, a stable `v1.0.0` release.
+This document defines the evidence required to move DocMergeForge from a development checkpoint to a release candidate and, eventually, an intentionally production-accepted release.
 
-A release is not complete merely because source tests pass or PyInstaller creates an archive.
+A release is not complete merely because source tests pass, a version number changes, or PyInstaller creates an archive.
 
 ## Release evidence levels
 
@@ -17,7 +17,9 @@ Documentation, changelogs, and releases must not collapse these levels into a si
 
 ## Versioning
 
-The project follows semantic-versioning intent. The package remains pre-stable (`0.x`) while the release matrix is being completed. `1.0.0` is reserved for the first intentionally accepted stable public contract.
+The current release-preparation target is `2.8.5`. DocMergeForge uses semantic-version-shaped package identifiers, but the repository's evidence model remains authoritative for readiness: a major version greater than zero or one does **not** by itself mean that human/production acceptance, signing/notarization, native mobile packaging, external-office fidelity, or claimed-scale stress gates have passed.
+
+The distribution classifier and release documentation must remain conservative until the corresponding evidence is accepted. For `2.8.5`, treat package/runtime metadata as a candidate identifier first; promote/tag/publish only after the intended release gates for that distribution claim are green and reviewed.
 
 ## 1. Freeze release scope
 
@@ -29,13 +31,16 @@ Review/update as appropriate:
 
 ```text
 pyproject.toml
+src/docmergeforge/__init__.py
+tests/unit/test_version_metadata.py
 CHANGELOG.md
 README.md
 docs/
+PROJECT_STATE.md
 what_changed.md
 ```
 
-Every documented command and support claim must match the candidate implementation.
+Every documented command and support claim must match the candidate implementation. Package metadata and runtime `__version__` must agree, and the release candidate should have an explicit regression pin so accidental version drift fails before publication.
 
 ## 3. Source quality and documentation gate
 
@@ -47,6 +52,7 @@ ruff check .
 black --check --diff .
 mypy src/docmergeforge
 python scripts/check_docs_links.py
+python scripts/check_repository_reference.py
 pytest --cov=docmergeforge --cov-report=term-missing
 ```
 
@@ -111,7 +117,7 @@ Run:        32033135355
 Checkpoint: 59dc14bbf1d4301177e475ac350694bdd9d90ada
 ```
 
-All Windows/macOS/Ubuntu build-host and fresh-runner jobs passed.
+All Windows/macOS/Ubuntu build-host and fresh-runner jobs passed for that historical checkpoint. Re-run/review candidate-appropriate packaging evidence before attributing it to `2.8.5`.
 
 ## 13. Optional onefile gate
 
@@ -124,7 +130,7 @@ Run:        32033541414
 Checkpoint: dc624e23d07e0ce94ef345245630d153ee60091a
 ```
 
-All Windows/macOS/Ubuntu build-host and fresh-runner jobs passed.
+All Windows/macOS/Ubuntu build-host and fresh-runner jobs passed for that historical checkpoint. Do not relabel it as `2.8.5` evidence unless the exact candidate commit is the checkpoint being verified.
 
 ## 14. Build provenance and SBOM gate
 
@@ -149,7 +155,7 @@ Before a production support claim, use representative clean end-user machines/VM
 
 ## 16. Platform signing/notarization gate
 
-Current artifacts are explicitly unsigned development builds.
+Current artifacts are explicitly unsigned development builds unless final-stage evidence says otherwise.
 
 ### Windows
 
@@ -185,7 +191,7 @@ Release notes should state supported platforms/architectures/build modes, worklo
 
 A `v*` tag can trigger packaging, but the tag itself is not acceptance and does not make current artifacts signed.
 
-Tag only the chosen reviewed commit after required gates for the release claim are green/accepted.
+Tag only the chosen reviewed commit after required gates for the release claim are green/accepted. For the current cycle, do not create or describe `v2.8.5` as accepted merely because package metadata says `2.8.5`.
 
 ## 21. Post-release verification
 
@@ -199,9 +205,11 @@ After publishing through the real user-facing channel:
 6. confirm no private/debug files were uploaded;
 7. retain run IDs, provenance/SBOM/checksums, trust evidence, and human acceptance records.
 
-## Stable `v1.0.0` gate
+## Production-acceptance gate
+
+Do not claim a production-accepted release until required areas for the intended support statement are intentionally accepted, including core merge correctness, transaction/recovery safety, representative large/stress workloads, real-world fidelity, human accessibility, downloaded-artifact and human clean-machine package acceptance, production signing/notarization where distributed, and complete documentation/support/security processes.
 
-Do not claim `v1.0.0` until required areas for the intended support statement are intentionally accepted, including core merge correctness, transaction/recovery safety, representative large/stress workloads, real-world fidelity, human accessibility, downloaded-artifact and human clean-machine package acceptance, production signing/notarization where distributed, and complete documentation/support/security processes.
+This gate applies to `2.8.5` regardless of its numeric major version.
 
 ## Release evidence template
 
@@ -210,6 +218,7 @@ Version/tag:
 Commit SHA:
 Date:
 Quality run:
+Project Sync Safety run:
 120-Part Regression run:
 Build Smoke run:
 Security run:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docmergeforge"
-version = "0.1.0"
+version = "2.8.5"
 description = "Local-first, validation-driven PDF and DOCX merger for large multi-part publications."
 readme = "README.md"
 requires-python = ">=3.12"

scripts/check_docx_fidelity_acceptance.py

@@ -13,9 +13,7 @@ def build_fixture(path: Path) -> None:
     document = Document()
     document.core_properties.title = "DocMergeForge Fidelity Acceptance"
     document.add_heading("Fidelity Acceptance", level=1)
-    document.add_paragraph(
-        "Representative smoke content with bold, italic, and list formatting."
-    )
+    document.add_paragraph("Representative smoke content with bold, italic, and list formatting.")
     formatted = document.add_paragraph()
     formatted.add_run("Bold text").bold = True
     formatted.add_run(" and ")

src/docmergeforge/__init__.py

@@ -1,3 +1,3 @@
 """DocMergeForge package."""
 
-__version__ = "0.1.0"
+__version__ = "2.8.5"

src/docmergeforge/cli/main.py

@@ -278,9 +278,7 @@ def _run_direct_merge(args: argparse.Namespace) -> int:
                         "ready": False,
                         "missing": validation_result.missing_parts,
                         "duplicates": validation_result.duplicate_parts,
-                        "diagnostics": [
-                            item.to_dict() for item in validation_result.diagnostics
-                        ],
+                        "diagnostics": [item.to_dict() for item in validation_result.diagnostics],
                     },
                     indent=2,
                 )

src/docmergeforge/diagnostics/logging.py

@@ -15,9 +15,7 @@
     r"(?P=quote)?"
 )
 _BEARER_PATTERN = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+")
-_AUTH_HEADER_PATTERN = re.compile(
-    r"(?i)\bAuthorization\s*:\s*(?:Basic|Bearer)\s+[^\s,;]+"
-)
+_AUTH_HEADER_PATTERN = re.compile(r"(?i)\bAuthorization\s*:\s*(?:Basic|Bearer)\s+[^\s,;]+")
 _API_KEY_HEADER_PATTERN = re.compile(r"(?i)\b(?:X-)?Api-Key\s*:\s*[^\s,;]+")
 
 

src/docmergeforge/discovery/scanner.py

@@ -58,9 +58,7 @@ def _iter_directory(
     for directory, directory_names, file_names in os.walk(root, followlinks=False):
         directory_path = Path(directory)
         directory_names[:] = [
-            name
-            for name in directory_names
-            if not _is_excluded(directory_path / name, excluded)
+            name for name in directory_names if not _is_excluded(directory_path / name, excluded)
         ]
         for name in file_names:
             path = directory_path / name

src/docmergeforge/docx/fidelity_acceptance.py

@@ -128,12 +128,8 @@ def snapshot_docx_structure(path: Path) -> DocxStructureSnapshot:
         inline_shapes=len(document.inline_shapes),
         sections=len(document.sections),
         headings=headings,
-        header_paragraphs=sum(
-            len(section.header.paragraphs) for section in document.sections
-        ),
-        footer_paragraphs=sum(
-            len(section.footer.paragraphs) for section in document.sections
-        ),
+        header_paragraphs=sum(len(section.header.paragraphs) for section in document.sections),
+        footer_paragraphs=sum(len(section.footer.paragraphs) for section in document.sections),
         header_tables=sum(len(section.header.tables) for section in document.sections),
         footer_tables=sum(len(section.footer.tables) for section in document.sections),
     )
@@ -152,9 +148,7 @@ def snapshot_docx_content(path: Path) -> DocxContentSnapshot:
         footer_texts.extend(_table_texts(section.footer.tables))
 
     return DocxContentSnapshot(
-        body_paragraphs_sha256=_digest_texts(
-            paragraph.text for paragraph in document.paragraphs
-        ),
+        body_paragraphs_sha256=_digest_texts(paragraph.text for paragraph in document.paragraphs),
         tables_sha256=_digest_texts(_table_texts(document.tables)),
         headers_sha256=_digest_texts(header_texts),
         footers_sha256=_digest_texts(footer_texts),

src/docmergeforge/docx/fidelity_corpus.py

@@ -67,11 +67,7 @@ def stopped_early(self) -> bool:
 
     @property
     def accepted(self) -> bool:
-        return (
-            self.discovered_count > 0
-            and not self.stopped_early
-            and self.failed_count == 0
-        )
+        return self.discovered_count > 0 and not self.stopped_early and self.failed_count == 0
 
     def to_dict(self) -> dict[str, Any]:
         return {

src/docmergeforge/docx/libreoffice_uno_acceptance.py

@@ -227,9 +227,7 @@ def run_libreoffice_uno_acceptance(
     capability = require_fidelity_automation("libreoffice")
     uno_python = find_uno_python()
     if uno_python is None:
-        raise ValidationError(
-            "LibreOffice UNO acceptance requires a Python UNO bridge."
-        )
+        raise ValidationError("LibreOffice UNO acceptance requires a Python UNO bridge.")
     libreoffice_uno_merge_documents(
         ordered,
         output,

src/docmergeforge/docx/libreoffice_uno_merge.py

@@ -20,7 +20,7 @@
 )
 from docmergeforge.utilities.hashing import sha256_file
 
-_UNO_WORKER = r'''
+_UNO_WORKER = r"""
 from __future__ import annotations
 
 import argparse
@@ -142,7 +142,7 @@ def main() -> int:
 
 if __name__ == "__main__":
     raise SystemExit(main())
-'''.strip()
+""".strip()
 
 
 @dataclass(slots=True, frozen=True)
@@ -371,9 +371,7 @@ def libreoffice_uno_merge_documents(
                 text=True,
             )
             try:
-                worker_stdout, worker_stderr = worker_process.communicate(
-                    timeout=timeout_seconds
-                )
+                worker_stdout, worker_stderr = worker_process.communicate(timeout=timeout_seconds)
             except subprocess.TimeoutExpired as exc:
                 worker_process.kill()
                 worker_stdout, worker_stderr = worker_process.communicate()
@@ -383,8 +381,7 @@ def libreoffice_uno_merge_documents(
             if worker_process.returncode != 0:
                 detail = worker_stderr.strip() or worker_stdout.strip()
                 raise ValidationError(
-                    "LibreOffice UNO merge worker failed"
-                    + (f": {detail}" if detail else ".")
+                    "LibreOffice UNO merge worker failed" + (f": {detail}" if detail else ".")
                 )
         finally:
             if worker_process is not None and worker_process.poll() is None:

src/docmergeforge/docx/section_evidence.py

@@ -68,9 +68,7 @@ def page_number_section_records(path: Path) -> tuple[PageNumberSectionRecord, ..
             try:
                 document_xml = archive.read(_DOCUMENT_XML)
             except KeyError as exc:
-                raise ValidationError(
-                    f"DOCX package is missing {_DOCUMENT_XML}: {path}"
-                ) from exc
+                raise ValidationError(f"DOCX package is missing {_DOCUMENT_XML}: {path}") from exc
     except zipfile.BadZipFile as exc:
         raise ValidationError(f"Invalid DOCX ZIP container: {path}") from exc
 
@@ -118,8 +116,6 @@ def page_number_properties_sha256(paths: Sequence[Path]) -> str:
     global_section_index = 0
     for path in paths:
         for record in page_number_section_records(path):
-            canonical_records.append(
-                f"section={global_section_index}|{record.canonical()}"
-            )
+            canonical_records.append(f"section={global_section_index}|{record.canonical()}")
             global_section_index += 1
     return _digest_records(canonical_records)

src/docmergeforge/docx/word_merge_acceptance.py

@@ -130,19 +130,15 @@ def _table_texts(tables: Iterable[Any]) -> list[str]:
 def _header_texts(document: Any) -> list[str]:
     values: list[str] = []
     for section in document.sections:
-        values.extend(
-            paragraph.text for paragraph in section.header.paragraphs if paragraph.text
-        )
+        values.extend(paragraph.text for paragraph in section.header.paragraphs if paragraph.text)
         values.extend(_table_texts(section.header.tables))
     return values
 
 
 def _footer_texts(document: Any) -> list[str]:
     values: list[str] = []
     for section in document.sections:
-        values.extend(
-            paragraph.text for paragraph in section.footer.paragraphs if paragraph.text
-        )
+        values.extend(paragraph.text for paragraph in section.footer.paragraphs if paragraph.text)
         values.extend(_table_texts(section.footer.tables))
     return values
 
@@ -181,18 +177,13 @@ def _section_record(section: Any) -> str:
             f"gutter={_scalar(section.gutter)}",
             f"header_distance={_scalar(section.header_distance)}",
             f"footer_distance={_scalar(section.footer_distance)}",
-            "different_first_page="
-            f"{int(bool(section.different_first_page_header_footer))}",
+            "different_first_page=" f"{int(bool(section.different_first_page_header_footer))}",
             f"header_linked={int(bool(section.header.is_linked_to_previous))}",
-            "first_header_linked="
-            f"{int(bool(section.first_page_header.is_linked_to_previous))}",
-            "even_header_linked="
-            f"{int(bool(section.even_page_header.is_linked_to_previous))}",
+            "first_header_linked=" f"{int(bool(section.first_page_header.is_linked_to_previous))}",
+            "even_header_linked=" f"{int(bool(section.even_page_header.is_linked_to_previous))}",
             f"footer_linked={int(bool(section.footer.is_linked_to_previous))}",
-            "first_footer_linked="
-            f"{int(bool(section.first_page_footer.is_linked_to_previous))}",
-            "even_footer_linked="
-            f"{int(bool(section.even_page_footer.is_linked_to_previous))}",
+            "first_footer_linked=" f"{int(bool(section.first_page_footer.is_linked_to_previous))}",
+            "even_footer_linked=" f"{int(bool(section.even_page_footer.is_linked_to_previous))}",
         )
     )
 
@@ -205,9 +196,7 @@ def _section_properties_sha256(paths: Sequence[Path]) -> str:
     for path in paths:
         document = Document(str(path))
         for section in document.sections:
-            records.append(
-                f"section={global_section_index}|{_section_record(section)}"
-            )
+            records.append(f"section={global_section_index}|{_section_record(section)}")
             global_section_index += 1
     return _digest_texts(records)
 
@@ -315,9 +304,7 @@ def _validate_acceptance_inputs(
     return ordered_sources
 
 
-def _verify_source_hashes(
-    sources: Sequence[Path], source_hashes: Sequence[str]
-) -> None:
+def _verify_source_hashes(sources: Sequence[Path], source_hashes: Sequence[str]) -> None:
     for source, expected_hash in zip(sources, source_hashes, strict=True):
         verify_native_source_unchanged(source, expected_hash)