release: v1.0.0 — Quartz Maturity (Stable) — GitHub Action

.github/workflows/self-check.yml

@@ -14,16 +14,48 @@ permissions:
   security-events: write  # required for upload-sarif
 
 jobs:
-  zenzic:
-    name: Documentation Quality Gate
-    runs-on: ubuntu-latest
+  verify:
+    name: Verify — ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Ubuntu: full verify (pre-commit + check + nox tests)
+          - os: ubuntu-latest
+            lint: true
+          # Windows: validate action logic and OS-level path handling only.
+          # pre-commit is skipped: Node hook (markdownlint) triggers thousands
+          # of small-file I/O operations that freeze the Windows runner.
+          # Linting is enforced by the Ubuntu slot.
+          - os: windows-latest
+            lint: false
+    defaults:
+      run:
+        shell: bash
+    # ZRT-010 — Sovereign Parity: Pre-Launch Guard lives in justfile.
+    # Local and CI run identical 'just check' invocations.
     steps:
       - uses: actions/checkout@v6
 
-      - name: Run Zenzic
-        uses: ./
-        with:
-          version: "0.7.0"
-          format: sarif
-          upload-sarif: "true"
-          fail-on-error: "true"
+      - name: Install just
+        uses: taiki-e/install-action@just
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Run unified verification
+        shell: bash
+        # Ubuntu: full verify (pre-commit + check + nox tests).
+        # Windows: skip pre-commit — Node hook freezes GHA Windows runners.
+        # Linting is enforced by the Ubuntu slot.
+        run: |
+          if [[ "${{ matrix.lint }}" == "true" ]]; then
+            just verify
+          else
+            just check
+            just test
+          fi

.gitignore

@@ -8,5 +8,24 @@ __pycache__/
 # nox
 .nox/
 
+# Coverage artefacts (Determinism Invariant — never tracked)
+coverage.json
+coverage.xml
+htmlcov/
+.coverage
+.coverage.*
+
 # Misc
 .DS_Store
+.zenzic.local.toml
+.zenzic.dev.toml
+
+# EPOCH 4 — draft vault (git-ignored, local reference only)
+.draft/
+
+# --- Ephemeral Artifacts (Machine Silence) ---
+zenzic-results.sarif
+mutmut*
+.mutmut-cache/
+.pytest_cache/
+.hypothesis/

.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev>
+# SPDX-License-Identifier: Apache-2.0
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--unsafe]
+      - id: check-json
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: mixed-line-ending
+      - id: no-commit-to-branch
+        args: ["--branch", "main"]
+        stages: [pre-commit]
+
+  - repo: https://github.com/fsfe/reuse-tool
+    rev: v6.2.0
+    hooks:
+      - id: reuse
+
+  - repo: local
+    hooks:
+      - id: zenzic-check
+        name: Zenzic Sentinel
+        entry: just check
+        language: system
+        pass_filenames: false
+        always_run: true
+
+  # Pre-push Final Guard (4-Gates Standard, EPOCH 4 / v0.7.0)
+  # Single entry-point: locale ≡ remote. Same `just verify` runs in GHA.
+  # Install with: uvx pre-commit install -t pre-push
+  - repo: local
+    hooks:
+      - id: just-verify
+        name: 🛡️ Action Final Guard (just verify)
+        entry: just verify
+        language: system
+        stages: [pre-push]
+        pass_filenames: false
+        always_run: true

CHANGELOG.md

@@ -0,0 +1,64 @@
+<!-- SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- markdownlint-disable MD024 -->
+# Changelog
+
+All notable changes to zenzic-action are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] — 2026-05-07 — Quartz Edition (Stable)
+
+> The official GitHub Action for [Zenzic](https://github.com/PythonWoods/zenzic),
+> the deterministic documentation quality gate.
+
+### 💎 Quartz Era (Initial Stable Release)
+
+This release establishes zenzic-action as a **stable, self-contained distribution
+channel** for the Zenzic Sentinel. The Action is decoupled from the core development
+cycle and pinned exclusively to released versions via `uvx zenzic@v0.7.0`.
+
+#### Added
+
+- **Composite GitHub Action** (`action.yml`): Installs Zenzic via `uv tool install`,
+  runs `check all` with configurable format, and optionally uploads SARIF results to
+  GitHub Code Scanning.
+- **Configurable Inputs**: `version`, `format` (`text`/`json`/`sarif`), `sarif-file`,
+  `upload-sarif`, `strict`, `fail-on-error`.
+- **Structured Outputs**: `sarif-file` path and `findings-count` for downstream steps.
+- **Path Traversal Guard**: `zenzic-action-wrapper.sh` rejects absolute paths and `..`
+  sequences in `sarif-file` input, preventing write-outside-workspace attacks.
+- **SARIF Integration**: Native `github/codeql-action/upload-sarif@v4` step surfaces
+  findings inline in PR diffs and the repository Security tab.
+- **4-Gates Standard**: `just verify` runs `reuse` + `check` + `preflight` + `test`
+  identically in local and CI environments.
+- **REUSE/SPDX Compliance**: All files carry inline SPDX headers. `REUSE.toml`
+  covers generated artefacts.
+- **Version Bump Automation**: `scripts/bump-version.sh` updates `action.yml` and
+  `README.md` version references atomically.
+
+#### Architecture
+
+- **Stable Pin Policy**: The Action invokes `uvx zenzic@v0.7.0` — never unreleased
+  code. This guarantees that downstream users always run against tested, tagged binaries.
+- **Zero Dynamic Coupling**: No checkout of the core repository. No `ZENZIC_PROJECT_PATH`.
+  No branch parity. The Action is a sealed distribution artefact.
+- **Self-Check CI** (`self-check.yml`): Validates the Action's own documentation using
+  the same stable Zenzic pin.
+
+#### Changed
+
+- **Matrix CI — Quartz Maturity**: `self-check.yml` now runs on `ubuntu-latest` and
+  `windows-latest` (`fail-fast: false`, `defaults: run: shell: bash`). Cross-platform
+  validation aligned with Core and Doc repos. `ZENZIC_EXTRA_ARGS` env block injected
+  with `--exclude-url` entries for known pre-launch transient URLs.
+- **Sovereign Override passthrough** (`zenzic-action-wrapper.sh`): `ZENZIC_EXTRA_ARGS`
+  is now captured into an `EXTRA_ARGS` bash array and passed to both the SARIF and
+  non-SARIF `uvx` invocations. Callers setting the 404 shield in their workflow env
+  have it transparently forwarded to the Zenzic CLI — no more silent bypass.
+- **`justfile` Bash-first**: `set shell := ["bash", "-c"]` added. `check *args` recipe
+  expanded with `${ZENZIC_EXTRA_ARGS:-}` for local parity with CI propagation.
+- **`.gitignore` hardening**: `.zenzic.dev.toml` added explicitly to prevent accidental
+  tracking. `.zenzic.local.toml` was already ignored. Local `.zenzic.dev.toml` purged.

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev>
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Contributing to zenzic-action
+
+Thank you for contributing to the official GitHub Action for Zenzic.
+
+## Core Dependency
+
+A differenza della documentazione, `zenzic-action` è vincolata alle release stabili del core. Per testare l'azione contro versioni non rilasciate del core, è necessario modificare temporaneamente il comando `uvx` nel workflow di test.
+
+This action relies on the published Zenzic CLI on PyPI. It acts as a stable wrapper to distribute Zenzic inside GitHub Actions securely.
+
+## First-Time Setup
+
+Install the pre-commit hooks (run once after cloning):
+
+```bash
+uvx pre-commit install               # commit-stage: hygiene + zenzic self-check
+uvx pre-commit install -t pre-push   # pre-push: 🛡️ Final Guard runs `just verify`
+```
+
+## Local Verification
+
+Use `just` to run the self-tests before opening a PR:
+
+```bash
+just lint      # fast pass: pre-commit hooks only
+just verify    # full gate: pre-commit + Zenzic check + integration tests
+```
+
+Both must pass with zero errors before you open or update a PR.