feat(rc3): Zenzic v0.4.0-rc3 — i18n anchor fix, multi-language snippets, Shield deep-scan, governance

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev>
+# SPDX-License-Identifier: Apache-2.0
+
+name: Bug Report
+description: Report unexpected behaviour in Zenzic's checks, output, or exit codes.
+title: "fix: <short description>"
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report a bug. Please fill in all required fields —
+        this allows us to reproduce and fix the issue quickly.
+
+  - type: input
+    id: version
+    attributes:
+      label: Zenzic version
+      description: Output of `zenzic --version`
+      placeholder: "0.4.0rc3"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+      placeholder: "3.13.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - macOS
+        - Windows
+      multiple: false
+    validations:
+      required: true
+
+  - type: dropdown
+    id: engine
+    attributes:
+      label: Documentation engine
+      description: Which adapter was in use when the bug occurred?
+      options:
+        - MkDocs (mkdocs.yml present)
+        - Zensical (zensical.toml present)
+        - Vanilla (no engine config)
+        - Not applicable / unsure
+      multiple: false
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Command run
+      description: The exact `zenzic` command that triggered the bug.
+      placeholder: "zenzic check all --strict"
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: What actually happened? Include the full terminal output if possible.
+      render: text
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: zenzic.toml (if any)
+      description: Paste your `zenzic.toml` content here (remove any secrets first).
+      render: toml
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Pre-submission checklist
+      options:
+        - label: I have searched existing issues and this is not a duplicate.
+          required: true
+        - label: I have reproduced the bug with the latest published version.
+          required: true

.github/ISSUE_TEMPLATE/docs_issue.yml

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev>
+# SPDX-License-Identifier: Apache-2.0
+
+name: Documentation Issue
+description: Report an error, gap, or unclear section in the Zenzic documentation.
+title: "docs: <short description>"
+labels: ["documentation", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Documentation issues are just as important as code bugs. Thank you for helping us
+        keep the docs accurate and clear.
+
+  - type: input
+    id: page
+    attributes:
+      label: Page or file
+      description: URL or file path of the documentation page with the issue.
+      placeholder: "https://zenzic.pythonwoods.dev/usage/advanced/ or docs/usage/advanced.md"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: issue_type
+    attributes:
+      label: Type of documentation issue
+      options:
+        - Incorrect information
+        - Missing information
+        - Outdated information
+        - Unclear or confusing explanation
+        - Broken link or missing asset
+        - Typo or formatting problem
+        - Missing Italian (it/) translation parity
+        - Other
+      multiple: false
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What is wrong or missing? Quote the specific text if relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested fix
+      description: >
+        Optional — if you know what the correct content should be, describe it here.
+        You can also open a pull request directly.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Pre-submission checklist
+      options:
+        - label: I have checked the latest published version of the docs at zenzic.pythonwoods.dev.
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,85 @@
+# SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev>
+# SPDX-License-Identifier: Apache-2.0
+
+name: Feature Request
+description: Propose a new check, adapter, Shield pattern, or CLI capability.
+title: "feat: <short description>"
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening a feature request, please open a discussion on the
+        [issue tracker](https://github.com/PythonWoods/zenzic/issues) so we can agree on
+        the approach before you invest time implementing it.
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Feature category
+      options:
+        - New check (link, orphan, snippet, placeholder, asset, references)
+        - New engine adapter (e.g. Hugo, Docusaurus)
+        - Shield — new credential family
+        - CLI command or flag
+        - Configuration option (zenzic.toml field)
+        - Custom rules DSL extension
+        - Performance improvement
+        - Developer / API
+        - Other
+      multiple: false
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What gap does this feature fill? What currently breaks or is missing?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: |
+        Describe the feature in concrete terms. If proposing a new adapter, describe the
+        entry-point registration, the `BaseAdapter` methods it must implement, and how
+        engine-specific config will be read.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What other approaches did you consider, and why did you rule them out?
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: pillars
+    attributes:
+      label: Zenzic design pillars
+      description: >
+        Zenzic's Core has three non-negotiable constraints. Please confirm your proposal
+        respects all that apply.
+      options:
+        - label: >
+            **Source-first** — the feature operates on raw source files; it does not require
+            a documentation engine to be installed or executed.
+        - label: >
+            **No subprocesses** — all logic uses pure Python or stdlib; no `subprocess.run`
+            calls in the linting path.
+        - label: >
+            **Pure functions** — core validation logic is deterministic, side-effect-free,
+            and testable without I/O.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Pre-submission checklist
+      options:
+        - label: I have searched existing issues and this is not already proposed.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,59 @@
+<!-- SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- markdownlint-disable MD041 -->
+
+## Description
+
+<!-- Describe your changes in detail. Link the issue this PR resolves. -->
+
+Closes #
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (new adapter, check, Shield pattern, CLI flag)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Refactor (no behaviour change)
+- [ ] Test coverage
+
+---
+
+## The Zenzic Way — mandatory checklist
+
+Zenzic's Core is built on three non-negotiable design pillars. Every PR that touches `src/`
+must satisfy all that apply.
+
+### 1. Source-first
+
+- [ ] This change operates on **raw source files** only — it does not call `mkdocs build`,
+  import a documentation framework, or depend on generated HTML or build artefacts.
+
+### 2. No subprocesses
+
+- [ ] No `subprocess.run`, `os.system`, or equivalent shell calls have been added to the
+  linting path (`src/zenzic/core/`).
+- [ ] Any new parsers use pure Python stdlib (e.g. `tomllib`, `json`, `yaml.safe_load`,
+  `compile()`).
+
+### 3. Pure functions
+
+- [ ] Core validation logic is **deterministic and side-effect-free**: no file I/O, no
+  network access, no global state mutations inside pure functions.
+- [ ] I/O is confined to CLI wrappers and scanner edges, not to validator or checker modules.
+
+---
+
+## Quality gates
+
+- [ ] `nox -s tests` passes (all existing tests green, coverage ≥ 80%).
+- [ ] New behaviour is covered by tests — happy path and at least one failure case.
+- [ ] `nox -s lint` and `nox -s typecheck` pass (`ruff check` + `mypy --strict`).
+- [ ] `nox -s preflight` passes end-to-end (includes `zenzic check all --strict` self-dogfood).
+- [ ] REUSE/SPDX headers are present on every new file (`nox -s reuse`).
+
+---
+
+## Notes for reviewers
+
+<!-- Anything unusual about this PR that reviewers should know? -->

.github/workflows/ci.yml

@@ -9,16 +9,20 @@ on:
     paths:
       - 'src/**'
       - 'tests/**'
+      - 'docs/**'
       - 'pyproject.toml'
       - 'uv.lock'
+      - 'noxfile.py'
       - '.github/workflows/ci.yml'
   pull_request:
     branches: [ main ]
     paths:
       - 'src/**'
       - 'tests/**'
+      - 'docs/**'
       - 'pyproject.toml'
       - 'uv.lock'
+      - 'noxfile.py'
       - '.github/workflows/ci.yml'
 
 permissions: