From dafc007144ffdc9b443271b846292be97ee572be Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Wed, 10 Jun 2026 20:15:18 +0200 Subject: [PATCH 1/9] chore(governance): eradicate Italian README/CONTRIBUTING and update configurations Signed-off-by: PythonWoods Signed-off-by: PythonWoods-Dev --- .gitignore | 72 ++++++++++----- .zenzic.toml | 2 +- CONTRIBUTING.it.md | 108 ---------------------- README.it.md | 226 --------------------------------------------- 4 files changed, 52 insertions(+), 356 deletions(-) delete mode 100644 CONTRIBUTING.it.md delete mode 100644 README.it.md diff --git a/.gitignore b/.gitignore index 2b1e42c..053ef40 100644 --- a/.gitignore +++ b/.gitignore @@ -1,36 +1,66 @@ # SPDX-FileCopyrightText: 2026 PythonWoods # SPDX-License-Identifier: Apache-2.0 -# Python bytecode +# ============================================================================ +# Zenzic Action — Git Ignore Rules +# ============================================================================ + +# ──────────────────────────────────────────────────────────────────────────── +# Environment Configuration +# ──────────────────────────────────────────────────────────────────────────── +.env +.env.local +.zenzic.local.toml +.zenzic.dev.toml + +# ──────────────────────────────────────────────────────────────────────────── +# AI Orchestration & Private Workspace (Zero-Leak Governance) +# ──────────────────────────────────────────────────────────────────────────── +# Private Tech Lead workspace +.architect/ +# Local AI routing rules (Trade Secret) +.clinerules +# Cursor AI rules (Trade Secret) +.cursorrules +# AI Primers and Memory ledgers +.github/agents/ +# Legacy draft vaults +.draft/ + +# ──────────────────────────────────────────────────────────────────────────── +# Python, Testing & Coverage +# ──────────────────────────────────────────────────────────────────────────── __pycache__/ *.pyc - -# nox .nox/ - -# Coverage artefacts (Determinism Invariant — never tracked) +.pytest_cache/ +.hypothesis/ 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/ -# VS Code Copilot agent definitions (local-only) -.github/agents/ -.zenzic_cache/ +# ──────────────────────────────────────────────────────────────────────────── +# Zenzic Artifacts (Machine Silence) +# ──────────────────────────────────────────────────────────────────────────── +# e.g., zenzic-results.sarif +*.sarif +# Zenzic local cache (external links, etc.) .zenzic_cache/ +# Derived local metadata +.zenzic-score.json + +# ──────────────────────────────────────────────────────────────────────────── +# IDEs & Operating System +# ──────────────────────────────────────────────────────────────────────────── +.DS_Store +.vscode/ +.idea/ +*.swp + +# ============================================================================ +# End of .gitignore +# ============================================================================ diff --git a/.zenzic.toml b/.zenzic.toml index 5917985..13a0e32 100644 --- a/.zenzic.toml +++ b/.zenzic.toml @@ -64,7 +64,7 @@ default_locale = "en" # --- BRAND INTEGRITY --- [project_metadata] release_name = "Magnetite" -badge_stamp_files = ["README.md", "README.it.md"] +badge_stamp_files = ["README.md"] [governance] # --------------------------------------------------------------------------- diff --git a/CONTRIBUTING.it.md b/CONTRIBUTING.it.md deleted file mode 100644 index f2f6a9e..0000000 --- a/CONTRIBUTING.it.md +++ /dev/null @@ -1,108 +0,0 @@ - - -# Contribuire a zenzic-action - -Grazie per il tuo contributo alla GitHub Action ufficiale di Zenzic. - -## Dipendenza Core - -La distribuzione runtime per gli utenti a valle resta agganciata alle release -pubblicate di Zenzic. I quality gate del repository (self-check, just, nox), -invece, usano il modello sovrano locale-core condiviso. - -La risoluzione della branch parity in CI segue questa precedenza: - -1. Override esplicito tramite la repository variable `ZENZIC_CORE_REF`. -2. Parità di nome del branch (`github.base_ref` o `github.ref_name`). -3. Fallback su `main` se il branch target non esiste in core. - -Usa `ZENZIC_CORE_REF` quando la nomenclatura dei branch di zenzic-action -diverge da quella dei repository core (ad esempio, branch di release -dell'action vs. branch di release del core). - -La governance dell'override è obbligatoria (fail-closed): quando -`ZENZIC_CORE_REF` è impostata, sono richieste le seguenti repository variables: - -1. `ZENZIC_CORE_REF_TICKET` (ticket di change/audit) -2. `ZENZIC_CORE_REF_REASON` (giustificazione esplicita) -3. `ZENZIC_CORE_REF_APPROVER` (owner che ha approvato) -4. `ZENZIC_CORE_REF_EXPIRES_ON` (data UTC in formato `YYYY-MM-DD`) - -Se i metadati mancano, sono malformati, scaduti o il branch non esiste in -core, la CI si arresta con un errore esplicito. - -## Policy di Governance Enterprise e Contributo - -Per garantire la sicurezza, l'integrità architetturale e la conformità legale di Zenzic, tutti i contributi devono aderire alle seguenti linee guida di Governance Enterprise: - -1. **Issue-First Policy (Prima le Issue)**: Nessuna Pull Request sarà presa in carico, revisionata o discussa se non preceduta da una Issue corrispondente discussa e approvata dai maintainer. Collega sempre l'Issue approvata nella descrizione della tua PR. -2. **Firma Crittografica Obbligatoria**: Tutti i commit devono essere firmati crittograficamente tramite chiavi GPG, SSH o S/MIME (mostrati come "Verified" su GitHub). I commit non firmati verranno respinti automaticamente dal gate di merge. -3. **Clausola "No AI Slop"**: Applichiamo una policy severa contro il codice generato da intelligenza artificiale non verificato. I contributor devono comprendere appieno, saper spiegare e giustificare dal punto di vista architetturale ogni singola riga di codice proposta nella PR. La proposta di codice non compreso porterà al rifiuto immediato del contributo. -4. **Developer Certificate of Origin (DCO)**: Tutti i commit devono includere la riga `Signed-off-by:` (usando `git commit -s`) per certificare la conformità con la DCO. -5. **Conventional Commits**: I messaggi di commit devono seguire rigorosamente la specifica Conventional Commits (es. `feat: add block anchor support (#123)`). - -## Setup Iniziale - -Installa gli hook pre-commit (una sola volta dopo il clone): - -```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` -``` - -Configura la firma SSH dei commit (obbligatoria — tutti i commit devono apparire come **Verified** su GitHub): - -```bash -# Configurazione globale una-tantum (salta se già configurata) -git config --global gpg.format ssh -git config --global user.signingkey ~/.ssh/id_ed25519.pub # adatta il percorso se necessario -git config --global commit.gpgsign true -``` - -Registra poi la tua chiave pubblica come **Signing Key** (non Authentication Key) su -. I commit firmati con una chiave non registrata -verranno rifiutati dal ruleset del branch. - -## Verifica Locale - -Usa `just` per eseguire i self-test prima di aprire una PR: - -```bash -just lint # fast pass: pre-commit hooks only -just verify # full gate: pre-commit + Zenzic check + integration tests -``` - -Entrambi devono passare con zero errori prima di aprire o aggiornare una PR. - -## Maintainer Only: Workflow Hardening - -### Immutable Pre-Commit Hooks (ADR-089) - -Tutte le chiavi `rev:` in `.pre-commit-config.yaml` devono puntare a un -**pin immutabile a commit hash**, mai a un tag semantico (`v1.2.3`). I tag git -sono mutabili: un maintainer upstream (o un attaccante) può spostare un tag -silenziosamente, avvelenando il Gate 2 locale senza alcun diff in questo -repository. - -Questa è una **policy CI interna del progetto zenzic-action**, non una regola -pubblica del linter Zenzic. Enforcement: `just check-pinning` (dipendenza di -`just verify`); le violazioni sollevano `[ADR-089] FATAL` in pre-push. - -La finestra di esposizione locale è più piccola di quella GHA perché -`pre-commit` congela i repo degli hook in `~/.cache/pre-commit/` finché -l'utente non lancia `autoupdate` o `clean`; GitHub Actions invece ri-risolve -il ref a ogni esecuzione. Il pinning è comunque obbligatorio in locale per la -sicurezza dei nuovi clone e per la parità con l'enforcement ADR-089 remoto. - -**Aggiornare gli hook pinned.** Non eseguire mai il `pre-commit autoupdate` -nudo — riscrive le SHA tornando a tag mutabili. Usa sempre: - -```bash -uvx pre-commit autoupdate --freeze -``` - -Questo preserva il commento di annotazione `# vX.Y.Z`. Committa il diff e -ri-verifica con `just check-pinning`. diff --git a/README.it.md b/README.it.md deleted file mode 100644 index f5737b8..0000000 --- a/README.it.md +++ /dev/null @@ -1,226 +0,0 @@ - - - - -

- - - - Zenzic / action - - -

- -

Il punto di enforcement deterministico per l'integrità della documentazione in CI. I codici di uscita sono contrattuali — exit 2 e 3 sopravvivono a fail-on-error: false.

- -

- ci-status - - zenzic-audit - - zenzic-score - action version - zenzic on PyPI - license - REUSE 3.x compliant -

- ---- - -Esegui i check Zenzic in CI e fai emergere i risultati direttamente in GitHub Code Scanning — senza leggere log. - -**Contratto exit code.** Il wrapper propaga i codici di uscita di Zenzic senza rimappatura. Exit 1 (qualità) obbedisce a `fail-on-error`. Exit 2 (credenziale) ed exit 3 (path traversal) terminano il job indipendentemente da `fail-on-error: false` o `--exit-zero` — i finding di sicurezza non vengono mai soppressi al boundary di enforcement. - -## Funzionalità Principali - -| Funzionalità | Descrizione | -|---|---| -| Install zero-setup | `uvx zenzic` — nessuna toolchain Python richiesta sul runner | -| Output SARIF | I finding alimentano direttamente GitHub Code Scanning | -| Contratto Exit Code | Gli incidenti di sicurezza (exit 2/3) non vengono mai soppressi da `fail-on-error` | -| Modalità Sovereign Audit | `audit: "true"` bypassa tutte le soppressioni — rivela il vero stato della documentazione | -| Check integrità SARIF | Valida il JSON prima dell'upload; emette `::warning` se troncato da SIGKILL | -| Annotation PR | Finding inline sul diff, codificati a colori per severità | -| Version pinning | Pin a una release esatta per gate CI deterministici e riproducibili | -| **Prosa pulita** | `[governance.directory_policies]` in `.zenzic.toml` concede esenzioni zero-debt a pattern di percorso | - -## Quick Start - -La configurazione minimale — zero setup Python, SARIF su Code Scanning in un solo step: - -```yaml title=".github/workflows/docs.yml" -- uses: actions/checkout@v6 - -- name: Run Zenzic Documentation Quality Gate - uses: PythonWoods/zenzic-action@v1 - with: - version: "0.10.4" - format: sarif - upload-sarif: "true" - permissions: - contents: read - security-events: write -``` - -Metti un file `.zenzic.toml` nella root del repository e l'action lo trova automaticamente — nessun input `config-file` richiesto. Esegui `zenzic init` una volta per fare scaffolding della configurazione se le tue docs sono fuori dalla cartella `docs/` di default. - -Per la configurazione avanzata (Configuration Discovery, Override Sovrano, scoring del Quality Gate, audit notturno), consulta la [documentazione di Zenzic Action](https://zenzic.dev/it/docs/reference/zenzic-action). - ---- - -## Policy Branch Protection (Operativa) - -Per il repository `zenzic-action`, proteggi `main` e abilita **Require status checks to pass before merging**. - -Check obbligatori: - -- `Verify (ubuntu-latest, true)` -- `Lint PR Title` -- `Check DCO` - -Intento operativo: - -- `Verify (ubuntu-latest, true)` è il gate di integrità funzionale per runtime action e comportamento del wrapper. -- `Lint PR Title` e `Check DCO` applicano governance e tracciabilità legale su ogni PR. - -Regola fail-closed: - -- Ogni check obbligatorio deve girare su `pull_request`. -- Non configurare la branch protection con check obbligatori provenienti da workflow solo tag, solo release o solo schedule. - ---- - -## Inputs - -| Input | Default | Descrizione | -|---|---|---| -| `version` | `0.10.4` | Versione di Zenzic da installare. Pin a una release specifica per esecuzioni deterministiche. Imposta `latest` per valutazione continua. | -| `format` | `sarif` | Formato di output: `text`, `json`, o `sarif`. | -| `sarif-file` | `zenzic-results.sarif` | Path di output SARIF (quando `format: sarif`). Deve essere un path **relativo** dentro il workspace. | -| `upload-sarif` | `true` | Carica SARIF su GitHub Code Scanning. | -| `strict` | `false` | Tratta i warning come errori. | -| `fail-on-error` | `true` | Fa fallire lo step del workflow sui finding. | -| `config-file` | *(auto)* | Path opzionale a un file di configurazione. Auto-scopre `.zenzic.toml` → `.github/.zenzic.toml` se omesso. | -| `audit` | `false` | Modalità sovereign audit: bypassa tutti i `zenzic:ignore` e `per_file_ignores`. Rivela il vero stato non filtrato della documentazione. Raccomandato per build notturne e workflow di security review. | -| `diff-base` | *(snapshot)* | Path a un file di baseline JSON per `zenzic diff`. Usa un artifact dal branch `main` per bloccare PR che aumentano il debito tecnico. Se omesso, usa `.zenzic-score.json`. | -| `guard-scan` | `false` | Esegue `zenzic guard scan` come step Defense-in-Depth **prima** del gate principale. Rileva credenziali hardcodate e pattern vietati che hanno bypassato i pre-commit hook. I finding di sicurezza falliscono con exit 2/3 e non sono governati da `fail-on-error`. | - -## Outputs - -| Output | Descrizione | -|---|---| -| `sarif-file` | Path al file SARIF generato. | -| `findings-count` | Numero totale di finding. | -| `score` | Documentation Quality Score (0–100). Disponibile con `format: json` o quando `diff-base` è impostato. | -| `suppression-debt-pts` | Punti di Debito Tecnico detratti dal punteggio per soppressioni attive. `0` quando non ci sono soppressioni. | -| `cap-exceeded` | `"true"` quando il CAP di soppressione è stato superato e ha bloccato la build; `"false"` altrimenti. | - -## Workflow Avanzati - -### Blocco della Regressione del Debito - -Blocca le pull request che aumentano il debito documentale. Salva una baseline da `main` come artifact del workflow; il job di quality-gate la scarica e fallisce se `zenzic diff` rileva un calo del punteggio. - -```yaml -jobs: - baseline: - runs-on: ubuntu-latest - if: github.ref == 'refs/heads/main' - steps: - - uses: actions/checkout@v4 - - name: Save score baseline - uses: PythonWoods/zenzic-action@v1 - with: - format: json - save: "true" - - uses: actions/upload-artifact@v4 - with: - name: zenzic-baseline - path: .zenzic-score.json - - quality-gate: - runs-on: ubuntu-latest - if: github.event_name == 'pull_request' - steps: - - uses: actions/checkout@v4 - - uses: actions/download-artifact@v4 - with: - name: zenzic-baseline - - name: Block debt regression - uses: PythonWoods/zenzic-action@v1 - with: - format: json - diff-base: .zenzic-score.json -``` - -### Audit Sovrano Notturno - -Esegui ogni notte un audit completo non filtrato per rivelare il vero stato della documentazione — bypassando tutti i commenti `zenzic:ignore` e i `per_file_ignores`. I finding soppressi nel CI quotidiano sono visibili qui. - -```yaml -on: - schedule: - - cron: "0 3 * * *" # 03:00 UTC ogni giorno - -jobs: - sovereign-audit: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Audit sovrano (nessuna soppressione) - uses: PythonWoods/zenzic-action@v1 - with: - audit: "true" - format: sarif - upload-sarif: "true" -``` - -### Utilizzo degli Output dell'Action - -Cattura `score`, `suppression-debt-pts` e `cap-exceeded` per logica condizionale o reportistica downstream. - -```yaml -steps: - - uses: actions/checkout@v4 - - - name: Zenzic quality gate - id: zenzic - uses: PythonWoods/zenzic-action@v1 - with: - format: json - fail-on-error: "false" - - - name: Report score - run: | - echo "Score: ${{ steps.zenzic.outputs.score }}/100" - echo "Suppression debt: ${{ steps.zenzic.outputs.suppression-debt-pts }} pts" - - - name: Fallisci se il CAP di soppressione è superato - if: steps.zenzic.outputs.cap-exceeded == 'true' - run: | - echo "::error::Suppression CAP superato — build bloccata." - exit 1 -``` - ---- - -## Codici di Uscita - -| Codice | Significato | Sopprimibile? | -|:---:|---|:---:| -| `0` | Tutti i check superati | — | -| `1` | Finding di documentazione (link rotti, orfani, CAP soppressioni) | Sì (`fail-on-error: "false"`) | -| **`2`** | **Credenziale rilevata (Z201)** | **Mai** | -| **`3`** | **Path traversal rilevato (Z202/Z203)** | **Mai** | - ---- - -Per la governance avanzata (Scoring & Debt, Sovereign Audit, Quality Gate PR blocking), consulta la -[documentazione di Zenzic Action](https://zenzic.dev/it/docs/reference/zenzic-action). - -Per gli internals dell'architettura di sicurezza (contratto exit code, Root-First discovery, guardia integrità SARIF), -consulta l'[Engineering Ledger](https://zenzic.dev/it/developers/explanation/adr-vault). - -## Licenza - -Apache-2.0 — vedi [LICENSE](LICENSE). From 255b2332276b3e836ddc8f79f8544f7074d937ad Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Wed, 10 Jun 2026 20:15:29 +0200 Subject: [PATCH 2/9] chore(release): remove root CHANGELOG.md from bumpversion configuration to prevent crashes Signed-off-by: PythonWoods Signed-off-by: PythonWoods-Dev --- .bumpversion.toml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index 4dc7268..8c3946d 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -6,11 +6,6 @@ current_version = "1.3.5" parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" serialize = ["{major}.{minor}.{patch}"] -[[tool.bumpversion.files]] -filename = "CHANGELOG.md" -search = "## [{current_version}]" -replace = "## [{new_version}]" - [[tool.bumpversion.files]] filename = "package.json" search = '"version": "{current_version}"' From 5f0bf2e9b2fdbfaab040eadcf2268d6697f5b075 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Wed, 10 Jun 2026 20:15:38 +0200 Subject: [PATCH 3/9] chore(governance): archive English v1.3.x history and clean root Changelog Signed-off-by: PythonWoods Signed-off-by: PythonWoods-Dev --- CHANGELOG.md | 47 +++-------------------------- changelogs/README.md | 10 +++++++ changelogs/v1.3.md | 71 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 43 deletions(-) create mode 100644 changelogs/README.md create mode 100644 changelogs/v1.3.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f2a15b1..b438446 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,7 @@ # 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/). +All notable changes to zenzic-action are documented in this file. The project adheres to Semantic Versioning. Major releases represent breaking changes to inputs/outputs, minor releases introduce new options or core package bumps, and patch releases address bug fixes. Format follows Keep a Changelog. --- @@ -15,44 +13,7 @@ No changes yet. --- -## [1.3.5] - 2026-06-09 +## Historical Releases -### Changed - -- **Operational governance docs:** Added explicit branch-protection policy to `README.md` and `README.it.md`, including required checks for `main` (`Verify (ubuntu-latest, true)`, `Lint PR Title`, `Check DCO`) and fail-closed workflow selection rules. -- **Core pin:** Zenzic Core pinned to `0.10.4`. - ---- - -## [1.3.5] - 2026-06-07 - -### Changed - -- Disabled dependency caching in `setup-uv` to prevent noisy warnings on non-Python repositories. - ---- - -## [1.3.5] - 2026-06-07 - -### Deprecated - -- **Versions v1.3.0 and older are officially deprecated.** They contained a critical bug in the bash wrapper that injected an invalid `--config` flag, causing false-positive Exit 2 crashes. Users pinned to exact patch versions must upgrade to `v1.3.1` or use the major tag `@v1`. - -### Added - -- `guard-scan` input: run `zenzic guard scan` before the main quality gate. -- `cap-exceeded` output: exposes suppression-cap failures for downstream workflow logic. -- Sovereign Job Summary output for every critical non-zero exit code. - -### Changed - -- Runtime governance parity: wrapper executes score governance checks after `check all`. -- ADR-037 alignment: `release_name` in `.zenzic.toml` set to semantic version form. -- ADR-089 alignment: GitHub Actions dependencies pinned to immutable SHA-40. -- Final Guard documentation aligned to the actual `just verify` recipe sequence. - -### Security - -- Explicitly documented non-suppressible action boundary for exits 2 and 3. -- Forwarding contract for security-related runtime flags is enforced end-to-end. -- Inherited governance semantics from core: additive `brand_obsolescence` merge behavior. +- v1.3.x archive: [changelogs/v1.3.md](./changelogs/v1.3.md) +- Archive index: [changelogs/README.md](./changelogs/README.md) diff --git a/changelogs/README.md b/changelogs/README.md new file mode 100644 index 0000000..ef83d9b --- /dev/null +++ b/changelogs/README.md @@ -0,0 +1,10 @@ + + + +# Historical Changelog Archives + +This directory contains per-minor-version changelog archives for zenzic-action. We divide our release history into archives to ensure that the main root changelog remains concise, readable, and focused on the current active release cycle. For the current release history, see the [main Changelog](../CHANGELOG.md). Older releases are listed below. + +| Version | Period | Archive | +|---------|--------|---------| +| v1.3.x | 2026-06-06 to 2026-06-09 | [v1.3.md](./v1.3.md) | diff --git a/changelogs/v1.3.md b/changelogs/v1.3.md new file mode 100644 index 0000000..7ea7534 --- /dev/null +++ b/changelogs/v1.3.md @@ -0,0 +1,71 @@ + + + +# Changelog Archive: v1.3.x + +## [1.3.5] - 2026-06-09 + +### Changed + +- **Operational governance docs:** Added explicit branch-protection policy to `README.md` and `README.it.md`, including required checks for `main` (`Verify (ubuntu-latest, true)`, `Lint PR Title`, `Check DCO`) and fail-closed workflow selection rules. +- **Core pin:** Zenzic Core pinned to `0.10.4`. + +--- + +## [1.3.4] - 2026-06-08 + +### Changed + +- **Core pin:** Zenzic Core pinned to `0.10.3`. +- **Governance:** Added conventional commits and commit signing setup documentation to `CONTRIBUTING.md` and `CONTRIBUTING.it.md`. + +--- + +## [1.3.3] - 2026-06-07 + +### Changed + +- **Core pin:** Zenzic Core pinned to `0.10.2`. + +--- + +## [1.3.2] - 2026-06-07 + +### Changed + +- Disabled dependency caching in `setup-uv` to prevent noisy warnings on non-Python repositories. + +--- + +## [1.3.1] - 2026-06-07 + +### Deprecated + +- **Versions v1.3.0 and older are officially deprecated.** They contained a critical bug in the bash wrapper that injected an invalid `--config` flag, causing false-positive Exit 2 crashes. Users pinned to exact patch versions must upgrade to `v1.3.1` or use the major tag `@v1`. + +### Added + +- `guard-scan` input: run `zenzic guard scan` before the main quality gate. +- `cap-exceeded` output: exposes suppression-cap failures for downstream workflow logic. +- Sovereign Job Summary output for every critical non-zero exit code. + +### Changed + +- Runtime governance parity: wrapper executes score governance checks after `check all`. +- ADR-037 alignment: `release_name` in `.zenzic.toml` set to semantic version form. +- ADR-089 alignment: GitHub Actions dependencies pinned to immutable SHA-40. +- Final Guard documentation aligned to the actual `just verify` recipe sequence. + +### Security + +- Explicitly documented non-suppressible action boundary for exits 2 and 3. +- Forwarding contract for security-related runtime flags is enforced end-to-end. +- Inherited governance semantics from core: additive `brand_obsolescence` merge behavior. + +--- + +## [1.3.0] - 2026-06-06 + +### Changed + +- Update action configuration to Magnetite codename. From 827d4a0207d54fd53c076dfbcd2edf2cc1af56ce Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Thu, 11 Jun 2026 18:23:48 +0200 Subject: [PATCH 4/9] chore(git): untrack private AI agent memory files and enforce gitignore Signed-off-by: PythonWoods Signed-off-by: PythonWoods-Dev --- .gitignore | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitignore b/.gitignore index 053ef40..810aefb 100644 --- a/.gitignore +++ b/.gitignore @@ -64,3 +64,7 @@ mutmut* # ============================================================================ # End of .gitignore # ============================================================================ + +# AI Agent Private Memory +.clinerules +.github/agents/ From 1d7a4d1e14e35d74d8f30b93a16357271f16032c Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 12 Jun 2026 19:11:17 +0200 Subject: [PATCH 5/9] chore: sync ledger updates for @site alias and Z102 anchor case-sensitivity Signed-off-by: PythonWoods Signed-off-by: PythonWoods-Dev --- .github/agents/memory/handoff_ledger.md | 45 +++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 .github/agents/memory/handoff_ledger.md diff --git a/.github/agents/memory/handoff_ledger.md b/.github/agents/memory/handoff_ledger.md new file mode 100644 index 0000000..7f51103 --- /dev/null +++ b/.github/agents/memory/handoff_ledger.md @@ -0,0 +1,45 @@ + + +# ZENZIC: ARCHITECTURAL HANDOFF LEDGER + +**TIMESTAMP:** 2026-06-10 +**TARGET AUDIENCE:** NEW AI INSTANCE (MAKER/ORCHESTRATOR) + +> **THE GOLDEN RULE OF MEMORY (OUROBOROS PROTOCOL):** +> At the conclusion of every sprint, bugfix, or architectural shift, the acting AI Agent MUST update this handoff_ledger.md file. Furthermore, this exact file MUST be synchronized identically across ALL THREE repositories (zenzic, zenzic-doc, zenzic-action). Failure to update and sync the ledger is classified as Tier 0 Technical Debt (Amnesia). + +## 1. CURRENT STATE (CRISTALLIZZATO) + +- **Versioning Law:** `zenzic` and `zenzic-doc` MUST share the exact same SemVer (e.g., v0.10.x). `zenzic-action` has an independent lifecycle (e.g., v1.x.y) but its `action.yml` default MUST point to the latest Core version. +- **Core Engine:** `v0.11.0-prep` +- **Documentation:** `v0.11.0-prep` +- **GitHub Action:** `v1.3.5` (Floating tag `@v1` forced to this commit) +- **Documentation:** Diátaxis framework strictly enforced. Legacy `` eradicated, 100% `` usage. +- **Governance:** Enterprise-grade. DCO (`-s`) and Cryptographic Signatures (`-S`) are mandatory and enforced by GitHub Branch Protection. PRs require an approved Issue (Issue-First Policy). + +## 2. ARCHITECTURAL BOUNDARIES + +- **Dynamic Sidebar Categories:** Zenzic operates strictly via static AST/I/O analysis (Pure Python). It cannot evaluate `sidebars.js/ts` to dynamically inject generated `/category/` routes into the VSM. Links to these virtual routes will yield Z101. Users should suppress Z101 on these specific links via `.zenzic.local.toml`. + +## 3. RECENT ARCHITECTURAL WINS (Do not regress) + +- **Docusaurus Native Routing Emulation:** Full support for `routeBasePath` concatenation, Frontmatter `slug` absolute/relative parsing, and Blog Date Extraction to map Docusaurus URLs into the Virtual Site Map without false positive broken links. +- **External Air-Gap Policy:** AI Agents are strictly forbidden from executing upstream contributions to third-party repositories. The AI drafts the payload; the Human Tech Lead executes the submission. +- **Python 3.12+ RE2 Compatibility:** Custom `translate_glob_to_re2` implemented. +- **DX Redesign:** Visual Progress Bar and `--breakdown` flag implemented. +- **Path-Aware Exclusion Engine:** `excluded_dirs` now supports `.gitignore` slash semantics for `repo_root`-relative targeting. +- **Monorepo Scalability:** Docusaurus dynamic root resolution implemented and baseline established. +- **AST Parser Fixes:** Z104 ignores footnotes (`[^1]:`). Z102 strips attribute lists (`{...}`) and supports explicit block anchors. Z302 tracks image nodes. +- **YAML Validator:** `_PermissiveSafeLoader` tolerates PyYAML custom tags (`!!python/name:`, `!ENV`) to support MkDocs configurations without throwing Z503. +- **CLI DX:** `--ci` is a macro-flag that implicitly sets `no_header = True`. +- **Z501 (Scunthorpe):** Default placeholder patterns are strictly `\bTODO\b` and `\bFIXME\b` using explicit RE2 word boundaries. + +## 4. ACTIVE TARGET: Next Sprint + +The next development cycle MUST focus exclusively on the following target: + +- [ ] *(Cleared)* + +## 5. KNOWN TECHNICAL DEBT (Backlog) + +- **OBOE (Off-By-One Error):** The snippet validator calculates error line numbers as `Block Start Line + Snippet Error Line`. There is a known +1 offset error (e.g., TOML error reported on line 220 instead of 219). Needs fixing in the AST node line extraction. From b2e2dcfa48f96fc64002f89153e415e022b361d9 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Fri, 12 Jun 2026 19:27:26 +0200 Subject: [PATCH 6/9] chore(git): enforce gitignore on local ledger Signed-off-by: PythonWoods Signed-off-by: PythonWoods-Dev --- .github/agents/memory/handoff_ledger.md | 45 ------------------------- 1 file changed, 45 deletions(-) delete mode 100644 .github/agents/memory/handoff_ledger.md diff --git a/.github/agents/memory/handoff_ledger.md b/.github/agents/memory/handoff_ledger.md deleted file mode 100644 index 7f51103..0000000 --- a/.github/agents/memory/handoff_ledger.md +++ /dev/null @@ -1,45 +0,0 @@ - - -# ZENZIC: ARCHITECTURAL HANDOFF LEDGER - -**TIMESTAMP:** 2026-06-10 -**TARGET AUDIENCE:** NEW AI INSTANCE (MAKER/ORCHESTRATOR) - -> **THE GOLDEN RULE OF MEMORY (OUROBOROS PROTOCOL):** -> At the conclusion of every sprint, bugfix, or architectural shift, the acting AI Agent MUST update this handoff_ledger.md file. Furthermore, this exact file MUST be synchronized identically across ALL THREE repositories (zenzic, zenzic-doc, zenzic-action). Failure to update and sync the ledger is classified as Tier 0 Technical Debt (Amnesia). - -## 1. CURRENT STATE (CRISTALLIZZATO) - -- **Versioning Law:** `zenzic` and `zenzic-doc` MUST share the exact same SemVer (e.g., v0.10.x). `zenzic-action` has an independent lifecycle (e.g., v1.x.y) but its `action.yml` default MUST point to the latest Core version. -- **Core Engine:** `v0.11.0-prep` -- **Documentation:** `v0.11.0-prep` -- **GitHub Action:** `v1.3.5` (Floating tag `@v1` forced to this commit) -- **Documentation:** Diátaxis framework strictly enforced. Legacy `` eradicated, 100% `` usage. -- **Governance:** Enterprise-grade. DCO (`-s`) and Cryptographic Signatures (`-S`) are mandatory and enforced by GitHub Branch Protection. PRs require an approved Issue (Issue-First Policy). - -## 2. ARCHITECTURAL BOUNDARIES - -- **Dynamic Sidebar Categories:** Zenzic operates strictly via static AST/I/O analysis (Pure Python). It cannot evaluate `sidebars.js/ts` to dynamically inject generated `/category/` routes into the VSM. Links to these virtual routes will yield Z101. Users should suppress Z101 on these specific links via `.zenzic.local.toml`. - -## 3. RECENT ARCHITECTURAL WINS (Do not regress) - -- **Docusaurus Native Routing Emulation:** Full support for `routeBasePath` concatenation, Frontmatter `slug` absolute/relative parsing, and Blog Date Extraction to map Docusaurus URLs into the Virtual Site Map without false positive broken links. -- **External Air-Gap Policy:** AI Agents are strictly forbidden from executing upstream contributions to third-party repositories. The AI drafts the payload; the Human Tech Lead executes the submission. -- **Python 3.12+ RE2 Compatibility:** Custom `translate_glob_to_re2` implemented. -- **DX Redesign:** Visual Progress Bar and `--breakdown` flag implemented. -- **Path-Aware Exclusion Engine:** `excluded_dirs` now supports `.gitignore` slash semantics for `repo_root`-relative targeting. -- **Monorepo Scalability:** Docusaurus dynamic root resolution implemented and baseline established. -- **AST Parser Fixes:** Z104 ignores footnotes (`[^1]:`). Z102 strips attribute lists (`{...}`) and supports explicit block anchors. Z302 tracks image nodes. -- **YAML Validator:** `_PermissiveSafeLoader` tolerates PyYAML custom tags (`!!python/name:`, `!ENV`) to support MkDocs configurations without throwing Z503. -- **CLI DX:** `--ci` is a macro-flag that implicitly sets `no_header = True`. -- **Z501 (Scunthorpe):** Default placeholder patterns are strictly `\bTODO\b` and `\bFIXME\b` using explicit RE2 word boundaries. - -## 4. ACTIVE TARGET: Next Sprint - -The next development cycle MUST focus exclusively on the following target: - -- [ ] *(Cleared)* - -## 5. KNOWN TECHNICAL DEBT (Backlog) - -- **OBOE (Off-By-One Error):** The snippet validator calculates error line numbers as `Block Start Line + Snippet Error Line`. There is a known +1 offset error (e.g., TOML error reported on line 220 instead of 219). Needs fixing in the AST node line extraction. From fd8016b63569f0e515f1f3cd436548532a302490 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Sat, 13 Jun 2026 13:14:07 +0200 Subject: [PATCH 7/9] fix: remove README.it.md from pin scripts Signed-off-by: PythonWoods-Dev --- justfile | 2 +- scripts/pin_core.py | 13 +------------ 2 files changed, 2 insertions(+), 13 deletions(-) diff --git a/justfile b/justfile index 9692ee6..0d745aa 100644 --- a/justfile +++ b/justfile @@ -50,7 +50,7 @@ pin-core version: fi echo "Aligning Zenzic Core pin to {{version}}..." uv run python scripts/pin_core.py {{version}} - git add action.yml README.md README.it.md .bumpversion.toml + git add action.yml README.md .bumpversion.toml git commit -m "chore(deps): pin zenzic core to {{version}}" # Simulate a Zenzic Core pin realignment and print the diff without writing files diff --git a/scripts/pin_core.py b/scripts/pin_core.py index de8d867..06eed77 100644 --- a/scripts/pin_core.py +++ b/scripts/pin_core.py @@ -82,18 +82,7 @@ def main() -> int: replacement=rf"\g<1>{version}\g<2>", min_matches=1, ), - FileUpdate( - path=repo_root / "README.it.md", - pattern=re.compile(r'(^\s{4}version: ")\d+\.\d+\.\d+("$)', re.MULTILINE), - replacement=rf"\g<1>{version}\g<2>", - min_matches=1, - ), - FileUpdate( - path=repo_root / "README.it.md", - pattern=re.compile(r'(\| `version` \| `)\d+\.\d+\.\d+(`)'), - replacement=rf"\g<1>{version}\g<2>", - min_matches=1, - ), + FileUpdate( path=repo_root / ".bumpversion.toml", pattern=re.compile( From db99b6784373a0926b5abe990c6f280eda77dfa3 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Sat, 13 Jun 2026 13:14:07 +0200 Subject: [PATCH 8/9] chore(deps): pin zenzic core to 0.11.0 Signed-off-by: PythonWoods-Dev --- .bumpversion.toml | 2 +- README.md | 4 ++-- action.yml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index 8c3946d..ef04ca7 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -23,4 +23,4 @@ regex = true # bump-my-version does NOT manage these files; they are listed here for discoverability. # --------------------------------------------------------------------------- [tool.bumpversion.custom_variables.core_version] -current = "0.10.4" +current = "0.11.0" diff --git a/README.md b/README.md index ae65911..c281a7b 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ The minimal configuration — zero Python setup, SARIF to Code Scanning in one s - name: Run Zenzic Documentation Quality Gate uses: PythonWoods/zenzic-action@v1 with: - version: "0.10.4" + version: "0.11.0" format: sarif upload-sarif: "true" permissions: @@ -94,7 +94,7 @@ Fail-closed rule: | Input | Default | Description | |---|---|---| -| `version` | `0.10.4` | Zenzic version to install. Pin to a specific release for reproducible CI. Set `latest` for continuous evaluation. | +| `version` | `0.11.0` | Zenzic version to install. Pin to a specific release for reproducible CI. Set `latest` for continuous evaluation. | | `format` | `sarif` | Output format: `text`, `json`, or `sarif`. | | `sarif-file` | `zenzic-results.sarif` | SARIF output path (when `format: sarif`). Must be a **relative** path inside the workspace. | | `upload-sarif` | `true` | Upload SARIF to GitHub Code Scanning. | diff --git a/action.yml b/action.yml index b2de682..9dcb9b8 100644 --- a/action.yml +++ b/action.yml @@ -16,7 +16,7 @@ inputs: version: description: "Zenzic version to use. Defaults to latest stable." required: false - default: "0.10.4" # x-zenzic-core-pin + default: "0.11.0" # x-zenzic-core-pin format: description: "Output format: 'text', 'json', or 'sarif'." required: false From 5a4c83387f470ebf3211cd2c064c1fc912618608 Mon Sep 17 00:00:00 2001 From: PythonWoods-Dev Date: Sat, 13 Jun 2026 13:14:10 +0200 Subject: [PATCH 9/9] release: bump version to 1.4.0 Signed-off-by: PythonWoods-Dev --- .bumpversion.toml | 2 +- RELEASE.md | 2 +- package.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index ef04ca7..889868d 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 [tool.bumpversion] -current_version = "1.3.5" +current_version = "1.4.0" parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" serialize = ["{major}.{minor}.{patch}"] diff --git a/RELEASE.md b/RELEASE.md index 55a7d86..d2ecaee 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -7,7 +7,7 @@ | Field | Value | | :------ | :--------- | | Version | v1.1.0 | -| Date | 2026-06-09 | +| Date | 2026-06-13 | | Status | Stable | ## Release Checklist diff --git a/package.json b/package.json index 4f1f260..07660a6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "zenzic-action", - "version": "1.3.5", + "version": "1.4.0", "private": true, "description": "Official GitHub Action for Zenzic — Documentation Quality Gate", "license": "Apache-2.0",