From f23cb1ba296169ca14ace84008b085cb6686730c Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 18:47:23 +0200 Subject: [PATCH 1/7] docs(diataxis): formalize the ontological boundary of static analysis regarding React and MDX Signed-off-by: PythonWoods --- .github/agents/memory/handoff_ledger.md | 48 +++++++++++++++++++++++++ 1 file changed, 48 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..a535d76 --- /dev/null +++ b/.github/agents/memory/handoff_ledger.md @@ -0,0 +1,48 @@ + + +# 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.12.0-prep` +- **Documentation:** `v0.12.0-prep` +- **GitHub Action:** `v1.4.0` (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`. + - See ADR-080-inversion-of-control.md for the permanent strategic solution (The Bridge Architecture). +- **React Runtime Invisibility:** Zenzic's AST parser cannot see DOM nodes (e.g., `id` attributes) generated dynamically by React components (like ``). Links targeting these nodes will yield `Z102`. +- **MDX Bundler Invisibility:** Zenzic parses files in isolation. It does not resolve MDX `import` statements to aggregate anchors from partials into the parent file. Links targeting partial anchors will yield `Z102`. + +## 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: + +- [ ] Implement ADR-080 (The Bridge Architecture) via `docusaurus-plugin-zenzic`. + +## 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 db30542c8276018b41bfad632a3aa9b3021b5a64 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 19:09:03 +0200 Subject: [PATCH 2/7] chore: sync handoff ledger for docusaurus eradication Signed-off-by: PythonWoods --- .github/agents/memory/handoff_ledger.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/.github/agents/memory/handoff_ledger.md b/.github/agents/memory/handoff_ledger.md index a535d76..79c7592 100644 --- a/.github/agents/memory/handoff_ledger.md +++ b/.github/agents/memory/handoff_ledger.md @@ -2,7 +2,7 @@ # ZENZIC: ARCHITECTURAL HANDOFF LEDGER -**TIMESTAMP:** 2026-06-10 +**TIMESTAMP:** 2026-06-13 **TARGET AUDIENCE:** NEW AI INSTANCE (MAKER/ORCHESTRATOR) > **THE GOLDEN RULE OF MEMORY (OUROBOROS PROTOCOL):** @@ -19,19 +19,18 @@ ## 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`. - - See ADR-080-inversion-of-control.md for the permanent strategic solution (The Bridge Architecture). -- **React Runtime Invisibility:** Zenzic's AST parser cannot see DOM nodes (e.g., `id` attributes) generated dynamically by React components (like ``). Links targeting these nodes will yield `Z102`. -- **MDX Bundler Invisibility:** Zenzic parses files in isolation. It does not resolve MDX `import` statements to aggregate anchors from partials into the parent file. Links targeting partial anchors will yield `Z102`. + + +- **Ontological Incompatibility (Docusaurus Eradicated):** Zenzic strictly targets Pure Static Documentation Engines (e.g., MkDocs, Sphinx, Zensical). SPA/MDX frameworks that generate DOM elements at runtime via JavaScript/React (e.g., Docusaurus) are ontologically out-of-scope, as they mathematically prevent zero-false-positive static analysis. Support for Docusaurus has been completely removed in v0.12.0. ## 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`. @@ -41,7 +40,7 @@ The next development cycle MUST focus exclusively on the following target: -- [ ] Implement ADR-080 (The Bridge Architecture) via `docusaurus-plugin-zenzic`. +- [x] Surgical Eradication of Docusaurus completed (v0.12.0). ## 5. KNOWN TECHNICAL DEBT (Backlog) From cd94e75274344bab5c903fc355c9ee747d3aac15 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 19:21:10 +0200 Subject: [PATCH 3/7] docs(blog): secure the docusaurus deprecation manifesto and define mkdocs migration bridge Signed-off-by: PythonWoods --- .github/agents/memory/handoff_ledger.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/agents/memory/handoff_ledger.md b/.github/agents/memory/handoff_ledger.md index 79c7592..24c428e 100644 --- a/.github/agents/memory/handoff_ledger.md +++ b/.github/agents/memory/handoff_ledger.md @@ -19,13 +19,10 @@ ## 2. ARCHITECTURAL BOUNDARIES - - - **Ontological Incompatibility (Docusaurus Eradicated):** Zenzic strictly targets Pure Static Documentation Engines (e.g., MkDocs, Sphinx, Zensical). SPA/MDX frameworks that generate DOM elements at runtime via JavaScript/React (e.g., Docusaurus) are ontologically out-of-scope, as they mathematically prevent zero-false-positive static analysis. Support for Docusaurus has been completely removed in v0.12.0. ## 3. RECENT ARCHITECTURAL WINS (Do not regress) - - **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. @@ -41,6 +38,8 @@ The next development cycle MUST focus exclusively on the following target: - [x] Surgical Eradication of Docusaurus completed (v0.12.0). +- [ ] Tactical Bridge: zenzic-doc will migrate to MkDocs Material to immediately restore CI linting and ADR-020 (i18n) compliance. +- [ ] Strategic Goal: Final migration to Zensical is deferred until Zensical achieves i18n parity. ## 5. KNOWN TECHNICAL DEBT (Backlog) From c813136979f250d9bbfec4fdebd9eb47372911c4 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 19:43:46 +0200 Subject: [PATCH 4/7] chore(deps): pin zenzic core to 0.12.0 --- .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 889868d..dfc42fe 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.11.0" +current = "0.12.0" diff --git a/README.md b/README.md index c281a7b..7d37faf 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.11.0" + version: "0.12.0" format: sarif upload-sarif: "true" permissions: @@ -94,7 +94,7 @@ Fail-closed rule: | Input | Default | Description | |---|---|---| -| `version` | `0.11.0` | Zenzic version to install. Pin to a specific release for reproducible CI. Set `latest` for continuous evaluation. | +| `version` | `0.12.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 9dcb9b8..9ad9451 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.11.0" # x-zenzic-core-pin + default: "0.12.0" # x-zenzic-core-pin format: description: "Output format: 'text', 'json', or 'sarif'." required: false From cb7f27ef94fe86b1f78294a6b825dcfc67547a19 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 19:44:20 +0200 Subject: [PATCH 5/7] chore(release): publish v2.0.0 major release (drops docusaurus) Signed-off-by: PythonWoods --- .bumpversion.toml | 2 +- CHANGELOG.md | 7 +++++-- package.json | 2 +- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.bumpversion.toml b/.bumpversion.toml index dfc42fe..e2f0660 100644 --- a/.bumpversion.toml +++ b/.bumpversion.toml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 [tool.bumpversion] -current_version = "1.4.0" +current_version = "2.0.0" parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" serialize = ["{major}.{minor}.{patch}"] diff --git a/CHANGELOG.md b/CHANGELOG.md index b438446..b6e97e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,12 @@ All notable changes to zenzic-action are documented in this file. The project ad --- -## [Unreleased] +## [2.0.0] - 2026-06-13 -No changes yet. +### Changed (Breaking) + +- **Dropped Docusaurus Support**: Upgraded the pinned Zenzic Core to `v0.12.0`, which surgically eradicates the Docusaurus adapter due to ontological incompatibility (React-injected IDs and MDX partial merging). Projects still relying on Docusaurus MUST remain on the `v1` floating tag (`v1.3.x`). +- **Major Version Bump**: The action major version is bumped to `v2` to prevent breaking existing Docusaurus consumers tracking `v1`. --- diff --git a/package.json b/package.json index 07660a6..d0f570b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "zenzic-action", - "version": "1.4.0", + "version": "2.0.0", "private": true, "description": "Official GitHub Action for Zenzic — Documentation Quality Gate", "license": "Apache-2.0", From 05e803cb39b64e74345fb2704e10861e5b4d6dd6 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 19:45:03 +0200 Subject: [PATCH 6/7] chore: update handoff ledger for v2.0.0 Signed-off-by: PythonWoods --- .github/agents/memory/handoff_ledger.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/agents/memory/handoff_ledger.md b/.github/agents/memory/handoff_ledger.md index 24c428e..6495702 100644 --- a/.github/agents/memory/handoff_ledger.md +++ b/.github/agents/memory/handoff_ledger.md @@ -11,9 +11,9 @@ ## 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.12.0-prep` -- **Documentation:** `v0.12.0-prep` -- **GitHub Action:** `v1.4.0` (Floating tag `@v1` forced to this commit) +- **Core Engine:** `v0.12.0 (Stable)` +- **Documentation:** `v0.12.0 (Stable)` +- **GitHub Action:** `v2.0.0 (Stable)` (Floating tag `@v2` 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). From 2458c94594d7adfec83cba978831d3421681d353 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sat, 13 Jun 2026 19:46:50 +0200 Subject: [PATCH 7/7] chore: remove untracked configurations from version control --- .github/agents/memory/handoff_ledger.md | 46 ------------------------- .gitignore | 4 +++ 2 files changed, 4 insertions(+), 46 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 6495702..0000000 --- a/.github/agents/memory/handoff_ledger.md +++ /dev/null @@ -1,46 +0,0 @@ - - -# ZENZIC: ARCHITECTURAL HANDOFF LEDGER - -**TIMESTAMP:** 2026-06-13 -**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.12.0 (Stable)` -- **Documentation:** `v0.12.0 (Stable)` -- **GitHub Action:** `v2.0.0 (Stable)` (Floating tag `@v2` 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 - -- **Ontological Incompatibility (Docusaurus Eradicated):** Zenzic strictly targets Pure Static Documentation Engines (e.g., MkDocs, Sphinx, Zensical). SPA/MDX frameworks that generate DOM elements at runtime via JavaScript/React (e.g., Docusaurus) are ontologically out-of-scope, as they mathematically prevent zero-false-positive static analysis. Support for Docusaurus has been completely removed in v0.12.0. - -## 3. RECENT ARCHITECTURAL WINS (Do not regress) - -- **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. - -- **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: - -- [x] Surgical Eradication of Docusaurus completed (v0.12.0). -- [ ] Tactical Bridge: zenzic-doc will migrate to MkDocs Material to immediately restore CI linting and ADR-020 (i18n) compliance. -- [ ] Strategic Goal: Final migration to Zensical is deferred until Zensical achieves i18n parity. - -## 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. diff --git a/.gitignore b/.gitignore index 810aefb..0f4b279 100644 --- a/.gitignore +++ b/.gitignore @@ -68,3 +68,7 @@ mutmut* # AI Agent Private Memory .clinerules .github/agents/ + +# AI Agents Configuration +.github/agents/ +.clinerules