Merge pull request #30 from PythonWoods/fix/standardize-v0.5.0a3

feat: v0.5.0a3 — Smart Init, Mutation Campaign + Tiered QA Doctrine

Author: PythonWoods-Dev

.gitignore

@@ -70,6 +70,7 @@ ENV/
 # ────────────────────────────────────────────────────────────────────────────
 .pytest_cache/
 .pytest_tmp/
+.hypothesis/
 .coverage
 .coverage.*
 htmlcov/

CHANGELOG.md

@@ -13,13 +13,16 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ## [0.5.0a3] — 2026-04-03 — The Sentinel: Aesthetic Sprint, Parallel Anchors & Agnostic Target
 
-> **Sprint 13 + 14.** Two major tracks delivered in one tag.
+> **Sprint 13 + 14 + 15.** Three tracks delivered in one tag.
 > Track A — Performance & SDK: deterministic two-phase anchor validation, `zenzic.rules` public
 > namespace, plugin scaffold command, Z001/Z002 split.
 > Track B — Aesthetic & DX: Sentinel Palette with Slate/Indigo/Rose/Amber color identity,
 > unified banner telemetry, agnostic target mode (`zenzic check all README.md` or
 > `zenzic check all content/`), `.pre-commit-hooks.yaml`, native Material header via
 > `MutationObserver`, and two new example projects.
+> Track C — The Breathing Sentinel: native `col_start`/`match_text` propagation replacing
+> fragile regex workarounds, surgical caret rendering, traceback gutter with 2-space
+> padding, vertical breathing between findings, and a dedicated success-state panel.
 
 ### Added
 
@@ -74,6 +77,12 @@ Versions follow [Semantic Versioning](https://semver.org/).
   - `src/<module>/rules.py` module-level `BaseRule` template
   - minimal docs fixture and `zenzic.toml` so `zenzic check all` can run
 
+- **Smart Initialization — `zenzic init --pyproject`** — when `pyproject.toml`
+  exists, `zenzic init` interactively asks whether to embed configuration as a
+  `[tool.zenzic]` table instead of creating a standalone `zenzic.toml`.  Pass
+  `--pyproject` to skip the prompt.  `--force` overwrites an existing
+  `[tool.zenzic]` section.  Engine auto-detection works in both modes.
+
 - `examples/plugin-scaffold-demo/` — living scaffold output fixture for SDK
   integration checks and contributor onboarding.
 
@@ -82,6 +91,43 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
+- **Native Data Propagation — "The Breathing Sentinel"** (`reporter.py`,
+  `validator.py`, `scanner.py`, `rules.py`, `cli.py`) — replaced the fragile
+  `_extract_token()` regex workaround with native `col_start`/`match_text`
+  propagation from every checker through the full pipeline to the reporter.
+  Every regex match site now captures `m.start()` and `m.group()` at detection
+  time and stores them in the finding dataclass — no reverse-engineering from
+  error messages.
+
+- **`LinkInfo` NamedTuple** (`validator.py`) — new type
+  `(url, lineno, col_start, match_text)` replacing plain `tuple[str, int]`
+  throughout the validator pipeline.  `extract_links()` and
+  `extract_ref_links()` now return `list[LinkInfo]`.
+
+- **Widened dataclasses** — `LinkError`, `PlaceholderFinding`, `RuleFinding`,
+  `Violation`, and `Finding` all gained `col_start: int = 0` and
+  `match_text: str = ""` fields, propagated end-to-end.
+
+- **Traceback Gutter** (`reporter.py`) — increased gutter padding to 2 spaces
+  around the vertical line: `16  ❱  code` / `16  │  code`.
+
+- **Vertical Breathing** (`reporter.py`) — empty `Text()` lines inserted
+  between different findings in the same file, before/after code snippets,
+  after file-separator rules, and before the verdict line.
+
+- **Success State** (`reporter.py`) — when all checks pass, the panel renders
+  a dedicated all-clear layout: telemetry → rule → elegant
+  `✔ All checks passed. Your documentation is secure.` message.
+
+- **Surgical Caret Rendering** (`reporter.py`) — `_render_snippet()` uses
+  native `col_start`/`match_text` to render precise `^^^^` caret underlines;
+  carets are suppressed when `col_start + len(match_text) > 60` (wrapping
+  guard) or when `match_text` is empty (no position data available).
+
+- **Removed `_extract_token()`** (`reporter.py`) — deleted the `_TOKEN_RE`
+  regex pattern and `_extract_token()` function; removed `import re` from the
+  module.  The reporter no longer guesses token positions from message strings.
+
 - **Sentinel Gutter Reporter** (`reporter.py`) — source-line context block uses
   the Sentinel Palette consistently:
   - `│` separators and line numbers rendered in `SLATE`
@@ -159,6 +205,12 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- **mypy errors** — `list[object]` annotations on `security_line` and
+  `renderables` changed to `list[RenderableType]` (imported from
+  `rich.console`); `config.docs_dir` (type `Path`) wrapped with `str()` when
+  passed to `SentinelReporter(docs_dir=...)` which expects `str`.
+  `mypy src/` — 0 errors in 30 files.
+
 - **Exit-code under target mode** — `has_failures` now uses filtered findings
   (`errors > 0`) rather than `results.failed` (which counted off-target findings
   such as `zenzic.toml` classified as an unused asset when `docs_dir` was patched
@@ -170,12 +222,46 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ### Tests
 
+- `test_validator.py` updated: added `_ul()` helper to unwrap `LinkInfo` →
+  `(url, lineno)` tuples; 13 assertion patterns updated for `LinkInfo`
+  compatibility; 4 destructuring patterns migrated from `for u, _ in` to
+  `for link in` with `.url` attribute access.
 - 4 new CLI integration tests for target mode:
   `test_check_all_target_not_found`, `test_check_all_target_single_file`,
   `test_check_all_target_file_outside_docs`, `test_check_all_target_directory`.
 - Test fixtures write ≥ 60-word bodies to avoid `short-content` placeholder warnings.
-- **587 tests pass.** `just preflight` — all gates green:
-  ruff ✓ · mypy ✓ · pytest 81.49% coverage ✓ · REUSE ✓ · zenzic self-audit ✓ · mkdocs build --strict ✓.
+
+#### Mutation Testing Campaign — "The Mutant War"
+
+- **Mutation score: 86.7%** (242/279 mutants killed on `rules.py`) — up from
+  58.1% at baseline.  Target was 75%; exceeded by +11.7 pp.
+- **80 new mutant-killing tests** added to `test_rules.py`, organised in
+  dedicated test classes:
+  - `TestExtractInlineLinksWithLines` (14 tests) — edge cases for inline link
+    extraction including empty hrefs, escaped brackets, and multi-link lines.
+  - `TestVSMBrokenLinkRuleMutantKill` (22 tests) — `check_vsm` path/anchor
+    resolution logic, orphan detection, severity mapping, and `continue`/`break`
+    branch coverage.
+  - `TestAdaptiveRuleEngineRunMutantKill` (4 tests) — `AdaptiveRuleEngine.run()`
+    short-circuit and content propagation.
+  - `TestAdaptiveRuleEngineRunVsmMutantKill` (6 tests) — `run_vsm()` VSM-specific
+    finding collection and file iteration.
+  - `TestAssertPickleableMutantKill` (2 tests) — `assert_pickleable()` deep-copy
+    and `UNREACHABLE` assertion guard.
+  - `TestPluginRegistryMutantKill` (27 tests) — `PluginRegistry` discovery,
+    duplicate handling, case-sensitivity, and `validate_rule()` contract.
+  - `TestExtractLinksDeepMutantKill` (5 tests) — fence-block skipping, reference
+    link parsing, and empty-document edge cases.
+- **37 surviving mutants** classified as equivalent (no observable behaviour
+  change) or framework limitations (unreachable defensive assertions).
+- **Hypothesis property-based testing** integrated with three profiles:
+  `dev` (50 examples), `ci` (500), `purity` (1 000).
+- **mutmut 3.5.0** configured under `[tool.mutmut]` in `pyproject.toml`;
+  runner: `python3 -m pytest -x`, target: `src/zenzic/core/rules.py`.
+- **Performance baseline** relaxed from 150 ms → 200 ms for 5 000 in-memory
+  resolutions to accommodate CI/nox environmental variance (resolver is O(1)).
+- **706 tests pass.** `just preflight` — all gates green:
+  ruff ✓ · mypy ✓ · pytest 80%+ coverage ✓ · REUSE ✓ · zenzic self-audit ✓ · mkdocs build --strict ✓.
 
 ## [0.5.0a2] — 2026-04-03 — The Refined Sentinel: Lean Package & Unified Workflow
 

CITATION.cff

@@ -15,7 +15,7 @@ abstract: >
   scanner (the Shield). Built on pure functional principles in Python 3.11+, it operates
   source-first — no build framework required — and integrates with any Markdown-based
   documentation system via a plugin adapter protocol.
-version: 0.5.0a2
+version: 0.5.0a3
 date-released: 2026-04-03
 url: "https://zenzic.pythonwoods.dev/"
 repository-code: "https://github.com/PythonWoods/zenzic"

CONTRIBUTING.it.md

@@ -28,14 +28,17 @@ I controlli di qualità e le attività di sviluppo sono guidati da **just** (per
 | Sessione | Comando Just | Comando Nox | Descrizione |
 |---|---|---|---|
 | `dev` | - | `nox -s dev` | installa i pre-commit hook + scarica icone Lucide (da eseguire una volta dopo il clone) |
-| `tests` | - | `nox -s tests` | pytest + branch coverage |
+| `tests` | `just test` | `nox -s tests` | pytest + branch coverage (profilo Hypothesis **dev**) |
+| `tests` (approfondito) | `just test-full` | - | pytest con profilo Hypothesis **ci** (500 esempi) |
+| `mutation` | - | `nox -s mutation` | mutmut su `src/zenzic/core/rules.py` |
 | `lint` | `just lint` | `nox -s lint` | linting ruff + self-check zenzic |
 | `format` | - | `nox -s format` | formattazione ruff |
 | `typecheck` | - | `nox -s typecheck` | mypy strict |
 | `reuse` | - | `nox -s reuse` | conformità alle licenze REUSE/SPDX |
 | `security` | - | `nox -s security` | scansione vulnerabilità CVE pip-audit |
 | `docs` | `just dev` | `nox -s docs` | mkdocs build --strict |
 | `preflight` | `just deploy` | `nox -s preflight` | tutto quanto sopra |
+| `clean` | `just clean` | - | Rimuove `site/`, `dist/`, `.hypothesis/`, cache |
 | `screenshot` | - | `nox -s screenshot` | rigenera `docs/assets/screenshot.svg` |
 | `bump` | - | `nox -s bump -- patch` | avanza la versione + commit + tag |
 

CONTRIBUTING.md

@@ -39,12 +39,15 @@ the exact same environment as CI.
 |:-----|:---------------|:-----------------|:------------|
 | Bootstrap | `just sync` | — | Install / update all dependency groups |
 | **Self-lint** | **`just check`** | — | **Run Zenzic on its own documentation (strict)** |
-| Test suite | `just test` | `nox -s tests` | pytest + branch coverage |
+| Test suite | `just test` | `nox -s tests` | pytest + branch coverage (Hypothesis **dev** profile) |
+| Test suite (thorough) | `just test-full` | — | pytest with Hypothesis **ci** profile (500 examples) |
+| Mutation testing | — | `nox -s mutation` | mutmut on `src/zenzic/core/rules.py` |
 | Full pipeline | `just preflight` | `nox -s preflight` | lint, typecheck, tests, reuse, security |
 | **Pre-push gate** | **`just verify`** | — | **preflight + production build — run before every push** |
 | Docs build (fast) | `just build` | — | mkdocs build, no strict enforcement |
 | Docs build (prod) | `just build-prod` | `nox -s docs` | mkdocs build --strict, mirrors CI |
 | Docs serve | `just serve [port]` | `nox -s docs_serve` | live-reload server (default port 8000) |
+| Clean | `just clean` | — | Remove `site/`, `dist/`, `.hypothesis/`, caches |
 | Pre-commit setup | — | `nox -s dev` | install hooks + download Lucide icons (once after clone) |
 | Version bump | — | `nox -s bump -- patch` | bump version + commit + tag |
 | Screenshot | — | `nox -s screenshot` | regenerate `docs/assets/screenshot.svg` |
@@ -215,6 +218,44 @@ just build
 
 ---
 
+## Advanced QA: Mutants & Properties
+
+Zenzic uses two advanced testing techniques to ensure the Sentinel's core is battle-hardened.
+
+### Property-Based Testing (Hypothesis)
+
+`tests/test_properties.py` uses [Hypothesis](https://hypothesis.readthedocs.io/) to generate
+thousands of random inputs and verify **invariants** that must hold for any input:
+
+- `extract_links()` never crashes, always returns `LinkInfo`, line numbers stay in range.
+- `slug_heading()` is lowercase, idempotent, and free of leading/trailing hyphens.
+- `CustomRule.check()` returns valid findings with `col_start` in range.
+- `InMemoryPathResolver.resolve()` always returns a valid outcome type and catches path traversal.
+
+Run property tests:
+
+```bash
+uv run pytest tests/test_properties.py -x -q
+```
+
+### Mutation Testing (mutmut)
+
+[mutmut](https://mutmut.readthedocs.io/) modifies your source code (e.g. changes `>` to `>=`)
+and checks whether the test suite catches the mutation. A surviving mutant means a test gap.
+
+Target module: `src/zenzic/core/rules.py` — the heart of the Sentinel's detection logic.
+
+Run mutation testing:
+
+```bash
+nox -s mutation
+```
+
+**Merge requirement:** any new core rule must achieve a **mutation score > 90%**. If `mutmut`
+reports surviving mutants in `rules.py`, add targeted tests before merging.
+
+---
+
 ## Release procedure (maintainers only)
 
 Releases are **semi-automated**: the developer decides the bump type, one command does the rest.

README.it.md

@@ -167,6 +167,16 @@ Zenzic esegue un'**analisi statica** dei tuoi file di configurazione (`mkdocs.ym
 
 Questo significa che **non è necessario installare** MkDocs, Material for MkDocs o altri plugin di build nel tuo ambiente di linting. Zenzic rimane leggero e privo di dipendenze, rendendolo ideale per pipeline CI/CD veloci e isolate.
 
+### Setup progetto
+
+```bash
+zenzic init             # crea zenzic.toml con engine rilevato automaticamente
+zenzic init --pyproject # incorpora [tool.zenzic] in pyproject.toml
+```
+
+Quando `pyproject.toml` esiste, `zenzic init` chiede interattivamente se incorporare
+la configurazione lì. Usa `--pyproject` per saltare il prompt.
+
 ---
 
 ## Utilizzo CLI

README.md

@@ -362,6 +362,16 @@ This means you **do not need to install** MkDocs, Material for MkDocs, or any ot
 > (PDFs, ZIPs), add their glob patterns to `excluded_build_artifacts` in `zenzic.toml`
 > rather than pre-generating them. See the [First-Class Integrations](#first-class-integrations) section above.
 
+### Project setup
+
+```bash
+zenzic init             # creates zenzic.toml with auto-detected engine
+zenzic init --pyproject # embeds [tool.zenzic] in pyproject.toml instead
+```
+
+When `pyproject.toml` exists, `zenzic init` asks interactively whether to embed
+configuration there. Pass `--pyproject` to skip the prompt.
+
 ---
 
 ## CLI usage

RELEASE.md

@@ -112,6 +112,24 @@ serving as both a DX reference and a quality-gate integration test.
 
 ---
 
+#### ⚡ Smart Initialization — `zenzic init --pyproject`
+
+`zenzic init` now detects `pyproject.toml` in the project root and interactively
+asks whether to embed configuration as a `[tool.zenzic]` table instead of creating
+a standalone `zenzic.toml`.
+
+```bash
+zenzic init             # interactive: asks if pyproject.toml exists
+zenzic init --pyproject # skip the prompt, write directly into pyproject.toml
+zenzic init --force     # overwrite existing config (both modes)
+```
+
+Engine auto-detection (`mkdocs.yml` → `engine = "mkdocs"`, `zensical.toml` →
+`engine = "zensical"`) works in both standalone and pyproject modes.  When no
+engine config file is found, vanilla defaults apply.
+
+---
+
 #### 🛡️ Z001 / Z002 Split — Errors vs Warnings for Link Issues (closes #6)
 
 `VSMBrokenLinkRule` now distinguishes:
@@ -165,8 +183,9 @@ repos:
 ### Quality Gates
 
 ```text
-pytest             587 passed, 0 failed
-coverage           81.49% (gate: ≥ 80%)
+pytest             706 passed, 0 failed
+coverage           80%+ branch (gate: ≥ 80%)
+mutation score     86.7% (242/279 killed on rules.py — target: 75%)
 ruff check src/    0 violations
 mypy src/          0 errors
 reuse lint         262/262 files compliant
@@ -176,6 +195,31 @@ mkdocs build       --strict, 0 warnings
 
 ---
 
+### Mutation Testing Campaign — "The Mutant War"
+
+v0.5.0a3 ships with a full mutation testing campaign against `src/zenzic/core/rules.py`
+using **mutmut 3.5.0**.  The campaign raised the mutation score from 58.1% (baseline)
+to **86.7%** (242/279 killed) — exceeding the 75% target by +11.7 percentage points.
+
+**80 new targeted tests** were added to `test_rules.py`, organised in 7 specialised
+test classes covering:
+
+- **PluginRegistry** (27 tests) — discovery, duplicates, case-sensitivity, `validate_rule()`
+- **VSMBrokenLinkRule** (22 tests) — `check_vsm` path/anchor resolution, orphan detection
+- **Inline link extraction** (14 tests) — escaped brackets, empty hrefs, multi-link lines
+- **AdaptiveRuleEngine** (10 tests) — `run()` and `run_vsm()` short-circuits and propagation
+- **Deep link extraction** (5 tests) — fence-block skipping, reference links, empty documents
+- **Pickleable assertions** (2 tests) — deep-copy guard and `UNREACHABLE` sentinel
+
+The 37 surviving mutants were analysed and classified as equivalent mutations
+(no observable behaviour change) or framework-level limitations (unreachable
+defensive assertions).  **Practical quality saturation** has been reached.
+
+Hypothesis property-based testing is integrated with three severity profiles:
+`dev` (50 examples), `ci` (500), `purity` (1 000).
+
+---
+
 ## Why this release matters now
 
 The documentation tooling ecosystem is fractured. MkDocs 2.0 is on the horizon, carrying breaking
@@ -217,7 +261,7 @@ installed for `zenzic check all` to pass.
 
 All validation logic in Zenzic lives in pure functions: no file I/O, no network access, no global
 state, no terminal output. I/O happens only at the edges — CLI wrappers that read files and print
-findings. Pure functions are trivially testable (433 passing tests at 98.4% coverage), composable
+findings. Pure functions are trivially testable (706 passing tests, ≥ 80% branch-coverage gate), composable
 into higher-order pipelines, and deterministic across environments.
 
 The score you get on a developer laptop is the score CI gets. The score CI gets is the score you
@@ -543,8 +587,9 @@ and `diff` Python APIs has been renamed to `output_format` — update any progra
 
 ```text
 zenzic check all   # self-dogfood: 7/7 OK
-pytest             # 529 passed, 0 failed
-coverage           # ≥ 80% (hard gate)
+pytest             # 706 passed, 0 failed
+coverage           # ≥ 80% branch (hard gate)
+mutation score     # 86.7% (242/279 killed on rules.py)
 ruff check .       # 0 violations
 mypy src/          # 0 errors
 mkdocs build --strict  # 0 warnings

docs/community/contribute/pull-requests.md

@@ -57,7 +57,7 @@ by installing only what each job needs. The groups are:
 
 | Group | Contents | When to use |
 | :---- | :------- | :---------- |
-| `test` | `pytest`, `pytest-cov` | Running the test suite |
+| `test` | `pytest`, `pytest-cov`, `hypothesis`, `mutmut` | Running the test suite |
 | `lint` | `ruff`, `mypy`, `pre-commit`, `reuse` | Linting and type checking |
 | `docs` | MkDocs stack (`mkdocs-material`, etc.) | Building the documentation |
 | `release` | `nox`, `bump-my-version`, `pip-audit` | Releases and audits |
@@ -79,9 +79,20 @@ time:
 ```bash
 zenzic check all            # all seven checks
 zenzic check references     # includes custom [[custom_rules]] evaluation
-pytest                      # full test suite
+pytest                      # full test suite (Hypothesis dev profile — 50 examples)
 ```
 
+!!! tip "Thorough property-based testing"
+
+    To run the test suite with the **ci** Hypothesis profile (500 examples),
+    use `just test-full` or set the environment variable directly:
+
+    ```bash
+    just test-full
+    # or
+    HYPOTHESIS_PROFILE=ci pytest
+    ```
+
 !!! note "End users vs contributors"
 
     **End users** run `uvx zenzic check all` — no clone, no install, zero

docs/community/index.md

@@ -83,7 +83,7 @@ __Manual BibTeX:__
 @software{zenzic,
   author  = {PythonWoods},
   title   = {{Zenzic: The Agnostic Documentation Integrity Framework}},
-  version = {0.5.0a2},
+  version = {0.5.0a3},
   date    = {2026-04-03},
   url     = {https://zenzic.pythonwoods.dev/},
   license = {Apache-2.0},