PythonWoods · PythonWoods-Dev · Aug 2, 2026 · Aug 1, 2026 · Aug 1, 2026 · Aug 1, 2026
diff --git a/.bumpversion.toml b/.bumpversion.toml
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 [tool.bumpversion]
-current_version = "0.26.5"
+current_version = "0.27.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre_l>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre_l}{pre_n}",

diff --git a/.github/ISSUE_TEMPLATE/security_vulnerability.yml b/.github/ISSUE_TEMPLATE/security_vulnerability.yml
@@ -29,7 +29,7 @@ body:
     attributes:
       label: Zenzic version
       description: Output of `zenzic --version`
-      placeholder: "0.26.5"
+      placeholder: "0.27.0"
     validations:
       required: true
 

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -16,6 +16,7 @@ repos:
         args: [--unsafe]
       - id: check-json
       - id: check-toml
+        exclude: ^examples/
       - id: check-added-large-files
       - id: check-merge-conflict
       - id: check-case-conflict
@@ -26,6 +27,7 @@ repos:
     rev: f295829140d25717bc79368d3f966fc1f67a824f  # v0.41.0
     hooks:
       - id: markdownlint
+        exclude: ^examples/
         args: ["--fix"]
 
   # 3. Ruff (linting & formatting)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
@@ -7,7 +7,7 @@
 #
 #   repos:
 #     - repo: https://github.com/PythonWoods/zenzic
-#       rev: v0.26.5
+#       rev: v0.27.0
 #       hooks:
 #         - id: zenzic-verify    # quality gate — corrisponde a `just verify` lato zenzic
 #         - id: zenzic-guard     # fast staged-file credential scan

diff --git a/.zenzic.toml b/.zenzic.toml
@@ -27,6 +27,7 @@
 
 strict = true
 fail_under = 98
+max_sentence_length = 50
 # exit_zero = false
 # respect_vcs_ignore = true
 # validate_same_page_anchors = true
@@ -46,13 +47,9 @@ excluded_external_urls = [
 # --- EXCLUSION ZONES (Full bypass — use sparingly) ---
 excluded_file_patterns = []
 # Paths listed here are INVISIBLE to Zenzic: no findings, no audit trail.
-# Prefer [governance.per_file_ignores]
-
 [governance.directory_policies]
-"docs/assets/**" = ["Z405"]
-"docs/favicon.ico" = ["Z405"]
-"docs/blog/rss.xsl" = ["Z405"]
+"docs/blog/posts/**" = ["Z410", "Z411"]
+"docs/developers/explanation/adr-vault/records/**" = ["Z410", "Z411"]
+"docs/tutorials/examples/**" = ["Z410", "Z411"]
 "docs/tutorials/examples/z1xx-links/**" = ["Z107"]
-"docs/tutorials/examples/z5xx-content/**" = ["Z506", "Z503"]
-# Exempt reference file from syntax checks because it contains intentionally incorrect examples
-"docs/reference/finding-codes.md" = ["Z503"]
+"docs/tutorials/examples/z5xx-content/**" = ["Z506"]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,68 +11,32 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-## [0.26.5] - 2026-07-29
-
-### Fixed
-- **Supply Chain Integrity**: Emergency patch to replace a dirty build artifact published to PyPI in `v0.26.4`. No functional code changes.
-
-
-## [0.26.4] - 2026-07-29
-
-### Fixed
-
-- **LSP State Hygiene (`LSP-FIX-017`)**: Eradicated a race condition that caused "ghost diagnostics" to persist in the editor after a file or directory was deleted. The server now maintains a stateful tracker (`self.file_diagnostics`) and explicitly broadcasts empty diagnostic arrays (`[]`) for any URI that no longer exists in the Virtual Site Map.
-- **Inline Suppression Placement (`LSP-FIX-018`)**: Fixed a bug where the "Suppress this finding" Code Action injected the suppression comment on a new line, causing false-positive `Z603` (Dead Suppression) errors. The action now correctly appends the comment to the end of the offending line.
-
-## [0.26.3] - 2026-07-28
+## [0.27.0] - 2026-08-02
 
 ### Added
 
-- **Suppression Code Actions (`LSP-FEAT-003`)**: The LSP server now dynamically generates "Suppress this finding" Code Actions for all suppressible diagnostics. Clicking the action automatically injects the correct `<!-- zenzic:ignore:ZXXX -->` comment above the offending line. This feature is strictly disabled for `NON_SUPPRESSIBLE_CODES` (Z2xx Security findings) to enforce the security gate.
-
-### Fixed
-
-- **LSP State Hygiene (`LSP-FIX-015`)**: Eradicated "ghost diagnostics" by ensuring the LSP server explicitly sends an empty diagnostics array (`[]`) to VS Code when a file is deleted, clearing the PROBLEMS panel.
-- **Code Action Routing (`LSP-FIX-016`)**: Fixed a routing bug in the LSP server that prevented Quick Fixes for `Z108` (Empty Link Text) and `Z505` (Untagged Code Block) from appearing in the editor.
-- **Z603 Parity (`LSP-FIX-015`)**: Ensured HTML comment suppressions (`<!-- zenzic:ignore -->`) are correctly evaluated for "dead" status in the LSP engine.
-
-## [0.26.2] - 2026-07-28
+- **Smart Link Graph (`V0.27-01`)**: Transformed the Virtual Site Map (VSM) into a Smart Link Graph that tracks deterministic adjacency lists for outgoing links across document nodes.
+- **Configuration Validation Engine (`V0.27-04`)**: Introduced formal validation for `.zenzic.toml` with graceful degradation and non-suppressible diagnostic findings:
+  - `Z110` (CONFIG_SYNTAX_ERROR): Emitted on TOML syntax errors (`TOMLDecodeError`) with line-number extraction.
+  - `Z111` (CONFIG_SCHEMA_ERROR): Emitted on schema type mismatches and validation failures (`ValidationError`).
+  - Halts Markdown document graph scanning on fatal config errors to prevent false-positive cascades and protect LSP stability.
+- **Baseline & Regression Tracking (`V0.27-02`)**: Added deterministic snapshot baseline capability (`.zenzic-baseline.json`) via `--update-baseline` and `--baseline` CLI options. Computes line-shift invariant SHA-256 signatures for finding matching, tags baselined findings without dropping them (`Radical Unawareness`), and enforces DQS anti-regression exit rules in CI/CD.
+- **Mirror Law Parity (`ADR-020`)**: Authored 41 dedicated, deep-dive Rule Specification Cards (`docs/rules/ZXXX.md`) and updated `docs/reference/finding-codes.md` to achieve 100% Mirror Law documentation parity. Each card provides technical rationale, Bad/Good Markdown examples, and `.zenzic.toml` configuration options.
+- **Topological Connectivity Restoration**: Resolved `Z411` dead-end node findings across active documentation namespaces by injecting semantic `## See Also` navigation links within the AST graph.
 
 ### Fixed
 
-- **Extensionless Asset Resolution**: Fixed a bug in `VSMBrokenLinkRule._to_canonical_url` where extensionless files (e.g., `LICENSE`, `Makefile`) incorrectly received a trailing slash when `use_directory_urls` was active, causing false-positive `Z101` findings.
-
-## [0.26.1] - 2026-07-27
-
-### Added
-
-- **Adapter API Contract (`CORE-FIX-005`)**: Added the `use_directory_urls` property to the `BaseAdapter` contract. This allows adapters to explicitly declare their URL routing mode, eradicating encapsulation violations in the incremental engine.
-
-### Fixed
-
-- **URP Unification (`CORE-REFACTOR-003`)**: Eradicated the legacy CLI link validation pipeline (`validate_links_async`). Both CLI and LSP now evaluate broken internal links exclusively via `VSMBrokenLinkRule.check_vsm` and `PolyglotExtractor`, achieving 100% true validation parity.
-- **Asset Indexing Parity (`CORE-REFACTOR-006`)**: Upgraded the Virtual Site Map (VSM) builder to explicitly index non-Markdown static assets (e.g., `.png`, `.webp`, `.html`). This eradicates hardcoded directory workarounds and eliminates false-positive `Z101` and `Z104` findings for static assets across all adapters.
-- **JSON Purity (`CLI-FIX-001`)**: Enforced absolute JSON purity when the `--json` flag is active by routing `fail_under` and `suppression_cap` failure messages to `stderr`. This prevents `JSON.parse()` failures in programmatic consumers.
-- **MkDocs Asset URLs (`CORE-FIX-002`)**: Eradicated false-positive `Z101` findings for static assets in MkDocs repositories by preventing the `MkDocsAdapter` from appending trailing slashes to non-Markdown files during VSM route generation.
-
-### Documentation
-
-- **Blog Hero Image Standardization**: Added named hero assets for existing release posts, converted launch media from JPEG to WebP, and normalized hero-image alt text to a title-aligned editorial pattern across the blog.
-- **Editor Trilogy Article**: Added `docs/blog/posts/2026-07-27-editor-trilogy-v0240-v0260.md`, a Hostile Precision architectural synthesis of the v0.24.0 → v0.26.0 editor sequence, using the previously policy-exempt trilogy hero asset as an in-site referenced image.
-
-## [0.26.0] - 2026-07-26
-
-### Added
-
-- **CLI `--json` Shorthand Alias (`ECOSYSTEM-FEAT-002`)**: Added `--json` flag to `zenzic score` as an ergonomic shorthand for `--format json`. Emits a single deterministic `ScoreReport` JSON object on `stdout` without rich terminal formatting, designed for programmatic consumers and editor integrations.
+- **Readability Sentence Boundary Parser (`Z511`)**: Fixed sentence length calculation in `zenzic.core.content` by recognizing bulleted lists, numbered items, and blockquotes as hard sentence boundaries, eliminating false-positive readability warnings on long lists.
+- **CLI Flag Input Validation**: Enforced strict input validation for the `--only` CLI option in `zenzic check`, triggering an immediate fatal exit (`Exit 1`) when an invalid or unknown finding code is supplied.
+- **Topological Directory-Policy Tracking (`Z118`)**: Fixed a Core Engine governance bug where topological suppressions (`Z410`/`Z411`) could leave false-positive dead-policy findings by ensuring canonical tracker rebinding in scanner passes and paired topology policy consumption in `GlobalUsageTracker`.
 
-### Documentation
+### Changed
 
-- **CLI Reference Mirror Law Realignment (`ADR-020`)**: Updated `docs/reference/cli.md` with `--json` flag specifications, complete `zenzic score` flag table, and JSON Output Schema documentation.
-- **Roadmap Realignment (`ROADMAP-ALIGN-004`)**: Realigned `ROADMAP.md` to establish `[v0.26]` as *DQS Workspace UI*, shifting subsequent platform milestones (`v0.27`–`v0.30`).
+- **Zero-DBT Technical Debt Cleanup**: Reverted unauthorized configuration suppressions in `.zenzic.toml`, structurally resolved 48 empty section (`Z512`) findings across 35 Markdown files, and eliminated stale global suppressions (`Z118`).
 
 ## Historical Releases
 
+- v0.26.x archive: [changelogs/v0.26.x.md](./changelogs/v0.26.x.md)
 - v0.25.x archive: [changelogs/v0.25.x.md](./changelogs/v0.25.x.md)
 - v0.24.x archive: [changelogs/v0.24.x.md](./changelogs/v0.24.x.md)
 - v0.23.x archive: [changelogs/v0.23.x.md](./changelogs/v0.23.x.md)

diff --git a/CITATION.cff b/CITATION.cff
@@ -15,8 +15,8 @@ abstract: >-
   performs deterministic static analysis using a two-pass reference
   pipeline and a RE2-backed credential scanner, with zero subprocess
   calls and full SARIF 2.1.0 support for CI/CD integration.
-version: 0.26.5
-date-released: 2026-07-29
+version: 0.27.0
+date-released: 2026-08-02
 url: "https://zenzic.dev"
 repository-code: "https://github.com/PythonWoods/zenzic"
 repository-artifact: "https://pypi.org/project/zenzic/"

diff --git a/README.md b/README.md
@@ -5,11 +5,7 @@ SPDX-License-Identifier: Apache-2.0
 
 <p align="center">
   <a href="https://github.com/PythonWoods/zenzic">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="assets/brand/svg/zenzic-wordmark-dark.svg">
-      <source media="(prefers-color-scheme: light)" srcset="assets/brand/svg/zenzic-wordmark.svg">
-      <img src="assets/brand/svg/zenzic-wordmark.svg" alt="Zenzic" width="360">
-    </picture>
+    <img src="https://raw.githubusercontent.com/PythonWoods/zenzic/main/docs/assets/brand/svg/zenzic-logo.svg" alt="Zenzic Document Integrity Engine" width="480">
   </a>
 </p>
 
@@ -55,7 +51,7 @@ Zenzic detects broken links, orphaned pages, credential leaks, and structural in
 
 Zenzic is a unified, deterministic platform structured into three primary delivery mechanisms:
 
-- **[Core Engine (CLI)](#-installation)**: Python CLI, AST rule engine, and Virtual Site Map (VSM) topology analyzer.
+- **[Core Engine (CLI)](#-installation)**: Python CLI, AST rule engine, Virtual Site Map (VSM) topology analyzer, and **Baseline & Regression Tracking** (`.zenzic-baseline.json`).
 - **[VS Code Extension][zenzic-vscode]**: Real-time LSP client offering sub-50ms inline diagnostics, Quick Fixes, and DQS scoring.
 - **[GitHub Action][zenzic-action]**: Zero-config CI/CD quality gate with SARIF upload and PR annotations.
 
@@ -117,6 +113,10 @@ Zenzic treats documentation as a **security surface**. The tiered code model enf
 
 Zenzic reports only what is **statically verifiable** in the repository at scan time. It never infers intent or approximates link validity. Every finding is a falsifiable, reproducible fact.
 
+### Topological Graph Analysis (Orphans & Dead Ends)
+
+Beyond static file checks, Zenzic's Smart Link Graph builds an adjacency list to perform Breadth-First Search (BFS) over your document network. It identifies **Topological Orphans** (`Z410`, documents unreachable from navigation entry points) and **Dead Ends** (`Z411`, pages with no outgoing links), helping maintain structural navigation integrity.
+
 ---
 
 ## 🧠 Key Capabilities & Commands
@@ -143,7 +143,7 @@ Zenzic Core is headless and emits standardized **SARIF** JSON, ensuring seamless
       "tool": {
         "driver": {
           "name": "zenzic",
-          "version": "0.26.5",
+          "version": "0.27.0",
           "rules": [
             {
               "id": "Z101",
@@ -215,7 +215,7 @@ uv tool upgrade zenzic
 To run a specific version ephemerally without altering your global environment:
 
 ```bash
-uvx zenzic@0.26.5 check all
+uvx zenzic@0.27.0 check all
 ```
 
 ---
@@ -225,6 +225,7 @@ uvx zenzic@0.26.5 check all
 | Area | URL | Audience |
 | :--- | :--- | :--- |
 | 👤 User Guide | [zenzic.dev][docs-home] | Install, configure, CI/CD, finding codes |
+| 📜 Rule Specification Cards | [zenzic.dev/docs/rules][docs-rules] | 41 deep-dive rule specifications with Bad/Good remediation examples |
 | 🔧 Developer Portal | [zenzic.dev/developers][docs-developers] | Adapters, ADRs, CLI architecture |
 | 🛡️ Security | [SECURITY.md][security] | Security reviewer |
 
@@ -270,6 +271,7 @@ Apache-2.0 — see [LICENSE][license]. This project strictly adheres to Semantic
 [zenzic-vscode]:     https://marketplace.visualstudio.com/items?itemName=pythonwoods.zenzic-vscode
 [zenzic-action]:     https://github.com/PythonWoods/zenzic-action
 [docs-home]:         https://zenzic.dev/
+[docs-rules]:        https://zenzic.dev/docs/rules/
 [docs-arch]:         https://zenzic.dev/developers/how-to/implement-adapter
 [docs-developers]:   https://zenzic.dev/developers/
 [contributing]:      CONTRIBUTING.md

diff --git a/RELEASE.md b/RELEASE.md
@@ -8,9 +8,9 @@
 
 | Field    | Value      |
 | :------- | :--------- |
-| Version  | v0.26.5     |
+| Version  | v0.27.0     |
 | Codename | Magnetite   |
-| Date     | 2026-07-29 |
+| Date     | 2026-08-02 |
 | Status   | Stable |
 
 ## Release Checklist
@@ -21,7 +21,7 @@ Before tagging, every item must be green:
 - [ ] `zenzic lab all` — all 20 scenarios exit with expected code
 - [ ] `zenzic score --stamp` committed — badge in README.md reflects current score
 - [ ] `zenzic check all .` — zero findings in the repo root
-- [ ] `pyproject.toml` version matches the tag (`0.26.5`)
+- [ ] `pyproject.toml` version matches the tag (`0.27.0`)
 - [ ] `CITATION.cff` version and date updated
 - [ ] `CHANGELOG.md` — `[Unreleased]` section moved to the new version heading
 - [ ] Update SECURITY.md support table (Add new release, demote previous to Critical/EOL).
@@ -53,12 +53,12 @@ git checkout main
 git pull origin main
 
 # 3. Tag the main branch and push
-git tag -s -m "Release v0.26.5" v0.26.5
+git tag -s -m "Release v0.27.0" v0.27.0
 git push origin main --tags
 
 ```
 
-- [ ] Create GitHub Release from the tag, using the `## [0.26.5]` CHANGELOG section as the release body.
+- [ ] Create GitHub Release from the tag, using the `## [0.27.0]` CHANGELOG section as the release body.
 
 ## Changelog Reference
 

diff --git a/REUSE.toml b/REUSE.toml
@@ -6,7 +6,7 @@ version = 1
 # listed here.
 
 [[annotations]]
-path = [".zenzic-score.json", "coverage.json", ".markdownlint.json", "zenzic-output.schema.json"]
+path = [".zenzic-score.json", "coverage.json", ".markdownlint.json", "zenzic-output.schema.json", "zenzic-baseline.schema.json"]
 SPDX-FileCopyrightText = "2026 PythonWoods <dev@pythonwoods.dev>"
 SPDX-License-Identifier = "Apache-2.0"
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -10,7 +10,7 @@ SPDX-License-Identifier: Apache-2.0
 This document describes the planned milestone trajectory for Zenzic, the **Deterministic Document Integrity Engine and SAST for Markdown/MDX graphs**.
 Dates are targets, not commitments. All milestones are subject to revision.
 
-For the current release history and completed milestones (up to `v0.23.x`), see [CHANGELOG.md](CHANGELOG.md).
+For the current release history and completed milestones (up to `v0.26.x`), see [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
@@ -25,34 +25,7 @@ Before advancing the core feature set, the following infrastructural and validat
 
 ## Milestone Sequence
 
-### [v0.24] — Interactive Intelligence
-
-*Completing the diagnostic-to-remediation loop within the IDE.*
-
-- **VS Code Code Actions (Quick Fixes):** Implement `textDocument/codeAction` via LSP to allow users to instantly apply deterministic fixes (e.g., `Z121`, `Z603`) directly from the editor.
-
-### [v0.25] — LSP Stabilization & Hot-Reloading
-
-*Achieving 100% determinism between CLI and IDE via centralized governance, adapter-driven hot-reloading, and cross-platform URI parity.*
-
-- **Centralized Governance Pipeline:** Eliminate CLI vs. LSP diagnostic drift by extracting `directory_policies` and `per_file_ignores` into core governance evaluation.
-- **Adapter-Driven Config Hot-Reloading:** Enable real-time VSM topology rebuilds in VS Code when engine configuration files (e.g., `mkdocs.yml`, `zensical.toml`) change, without requiring an LSP server restart.
-- **BaseAdapter Contract Hardening:** Expose `watched_config_files` on the `BaseAdapter` interface to preserve Adapter Neutrality across third-party engines.
-
-### [v0.26] — DQS Workspace UI
-
-*Bringing the global Documentation Quality Score into the authoring environment via an asynchronous, deterministic CLI execution bridge.*
-
-- **Asynchronous CLI Execution Bridge:** Restore DQS visualization in the VS Code Status Bar via `child_process.execFile` calling `zenzic score --json`, guaranteeing 100% mathematical parity with CI/CD without blocking LSP performance.
-
-### [v0.27] — Deterministic Quality Platform
-
-*Evolving from a strict validator to a comprehensive quality governance engine.*
-
-- **Smart Link Graph:** Transform the Virtual Site Map (VSM) into a full topological analysis engine capable of detecting documentation islands, circular navigation paths, and unreachable clusters.
-- **Baseline & Regression Tracking:** Introduce evolutionary quality control. Essential for enterprise CI/CD to prevent DQS regressions over time.
-- **Semantic Readability Metrics:** Extend Zenzic beyond structural validation into content quality (e.g., deterministic Flesch-Kincaid scoring) while maintaining the static analysis paradigm.
-- **Configuration Validation Engine:** Reduce operational errors by establishing a single source of truth for configuration schemas across the CLI, VS Code, and documentation.
+> For completed milestones (`v0.23` through `v0.27`), see [CHANGELOG.md](CHANGELOG.md).
 
 ### [v0.28] — Governance & Extensibility
 
@@ -95,4 +68,4 @@ These constraints apply across every future release. No feature may violate them
 
 ---
 
-Roadmap last updated: 2026-07-25.
+Roadmap last updated: 2026-08-01.