Log convention — the terse mirror of RELEASE.md. For the narrative deep-dive, see Saga V — Beyond the Siege.

TL;DR. Zenzic v0.7.0 "Quartz Maturity" closes the post-Obsidian arc with seven epochs: the 4-Gates Standard (EPOCH 4), the language-agnostic Z907 I18N_PARITY check (EPOCH 5), Cross-Instance Sovereignty now Zero-Config (EPOCH 6), Multi-Root Discovery (EPOCH 7a), Zero-Config Sovereignty with [link_validation] removed (EPOCH 7a.1), and Virtual Routes with the zenzic inspect routes JSON API (EPOCH 7b). 1,485+ tests. Some breaking changes; clean migration path.

Breaking changes​

No silent deprecation shims. Industry-grade only.

EPOCH 4 — The Safe Port (4-Gates Standard)​

A single command runs every quality gate locally:

just verify

Sequence: pre-commit → pytest (with coverage) → zenzic check all --strict → exit-code parity self-test. The same four gates run in CI; what passes locally passes in the cloud.

EPOCH 5 — Z907 I18N_PARITY​

Language-agnostic translation parity check. Configure in zenzic.toml:

[i18n]
enabled = true
default_locale = "en"
locales = ["en", "it"]
parity_strict = true

When parity_strict = true, every page in default_locale must have a mirror in every other locale. Missing translations surface as Z907 I18N_PARITY findings.

EPOCH 6 — Cross-Instance Sovereignty (Zero-Config)​

Multi-instance Docusaurus setups (docs/, developers/, every additional @docusaurus/plugin-content-docs instance) are now fully supported without manual TOML configuration. DocusaurusAdapter.get_absolute_url_prefixes(repo_root) discovers every plugin's routeBasePath via static parsing of docusaurus.config.{ts,js,mjs,cjs} — zero subprocess, zero allowlist, zero duplication.

:::note Historical note An earlier draft of EPOCH 6 shipped a manual [link_validation].absolute_path_allowlist field. That approach was abandoned. The Zero-Config implementation superseded it entirely in EPOCH 7a.1. :::

EPOCH 7a — Multi-Root Discovery​

The VSM is no longer bounded by docs_dir. The Docusaurus adapter auto-detects the blog/ plugin via two pure-parsing passes (static regex over config, then convention fallback). Blog posts are first-class content: broken links inside blog/ and cross-tree links from docs/ to blog/ are caught by zenzic check all --strict. A Reverse-Mapping invariant test asserts every blog Route.source traces back to a real file on disk.

EPOCH 7a.1 — Zero-Config Sovereignty​

The [link_validation] TOML schema is removed. LinkValidationConfig and absolute_path_allowlist are gone from the codebase. Configs that still declare [link_validation] raise a TOML validation error. Migration: delete the block — DocusaurusAdapter discovers plugin URL prefixes automatically.

EPOCH 7b — Virtual Routes & zenzic inspect routes​

Engine-generated pages — tag indexes, paginated blog lists, author profiles — are now first-class VSM citizens with the Reverse-Mapping Invariant enforced at construction time. Three new finding codes:

New CLI command:

zenzic inspect routes [--kind physical|virtual|all] [--json]

Exports the complete site map as deterministic JSON with per-route url, kind, source_files (repo-relative POSIX), and digest. When --json is active, stdout is exclusively valid JSON — no ANSI codes, no banners.

Migration path​

The full migration matrix lives in RELEASE.md under "Breaking changes". One pass through the table is usually enough.

Saga deep-dive​

For the philosophy, the post-mortem of the AI-driven siege, and the engineering choices behind Quartz Maturity, see Saga V — Beyond the Siege.

During the final consolidation sprint for v0.7.0, we ran four AI agents against Zenzic's own documentation site. They were instructed to find everything wrong with it.

They found a file that Zenzic had marked REACHABLE. The file existed on disk, had valid frontmatter, and was not referenced by any broken link. By every metric in the pre-v0.7.0 implementation, it was clean.

The file had not appeared in the sidebar for three weeks. No navbar entry linked to it. No footer item referenced it. A user navigating the documentation site had no way to reach it by clicking. It was, from the reader's perspective, gone.

Zenzic was asking the wrong question.

The Wrong Question​

Traditional documentation linters ask: does the file exist on disk?

That is the correct question for a filesystem validator. It is the wrong question for a documentation integrity tool. Documentation is not a filesystem. It is an experience delivered through navigation surfaces — sidebar menus, navbar links, footer references. A file that exists on disk but appears on none of those surfaces is, for all practical purposes, invisible to every reader who visits your site.

Zenzic v0.7.0 asks a different question:

Can a user reach this file by clicking through the navigation of your documentation site?

If the answer is no, the file is an orphan — regardless of whether it exists on disk.

This is the UX-Discoverability Law.

Rule R21: The UX-Discoverability Law​

The formal rule, added to Zenzic's rule registry in D090:

R21 — UX-Discoverability: A file is REACHABLE if and only if at least one user-clickable navigation surface declares it. A file absent from all navigation surfaces is ORPHAN_BUT_EXISTING, regardless of its presence on disk.

For Docusaurus projects, "navigation surfaces" means exactly three sources:

Zenzic parses all three statically — no Node.js, no build step, no external process. The implementation is pure Python, respects Pillar 2 (zero subprocesses), and handles both .ts and .js sidebar files. JS-style comments are stripped before parsing. baseUrl and routeBasePath prefixes are normalised before path resolution.

A single frozenset[str] is returned to the Core, which applies the orphan rule uniformly across all engines. The Core knows nothing about sidebars, navbars, or footers. It receives a set of navigable paths and compares them against disk contents. That is the entire contract.

The Three-Surface Parser in Practice​

Given a project with an explicit sidebars.ts that deliberately omits changelog.mdx:

// sidebars.ts — changelog is not listed
const sidebars = {
  docs: ['intro', 'guide/index', 'guide/deploy'],
};
export default sidebars;

And a docusaurus.config.ts that links it from the navbar:

themeConfig: {
  navbar: {
    items: [
      { to: '/docs/changelog', label: 'Changelog', position: 'right' },
    ],
  },
},

Pre-v0.7.0: changelog.mdx → ORPHAN_BUT_EXISTING (not in sidebar).

Post-v0.7.0: changelog.mdx → REACHABLE (navbar declares it).

The same logic applies to footer-only files. A legal notice linked only in the footer has been invisible to Zenzic's orphan detector until now. In v0.7.0, it is REACHABLE because a user can reach it by clicking.

Architectural Philosophy: A Different Axis​

Documentation quality tools exist on a spectrum. Most operate on one axis — link existence — and stop there. Zenzic operates on a different axis entirely: trust.

markdown-link-check and htmlproofer are correct tools for what they declare. They are link checkers — fast, composable, well-understood. Zenzic is not a link checker that also happens to check orphans and scan for secrets. It is a Static Analysis Framework built on a fundamentally different trust model. Comparing them on a feature checklist alone is like comparing a compiler and a formatter because both read source files.

The meaningful comparison is architectural:

The choice of which tool to run depends on which question you need to answer. If the question is "do these links resolve?", a link checker is the right tool. If the question is "is this documentation safe, complete, and navigable?", the trust model matters — and Zero-Trust is the only honest answer when documentation is produced by teams, contributors, or automated agents you do not fully control.

The Safe Harbor: What v0.7.0 Completes​

The term "Safe Harbor" has been in Zenzic's vocabulary since the first engineering post. This is what it means in v0.7.0:

This is not a list of aspirational features. Each row has a test class, a CHANGELOG entry, and a decision record documenting the architectural choice that makes it true.

SARIF: Documentation Quality in Your Security Dashboard​

Starting with v0.7.0, every zenzic check command supports --format sarif:

zenzic check all ./docs --format sarif > results.sarif

The output is valid SARIF 2.1.0, consumable directly by GitHub Code Scanning. Add this to your CI workflow:

- name: Run Zenzic

  run: uvx zenzic check all ./docs --format sarif > zenzic.sarif

- name: Upload SARIF

  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: zenzic.sarif

Your documentation findings — broken links, orphan pages, credential fragments, missing assets — appear in the Security tab of your repository, tracked alongside code vulnerabilities. Findings are filterable by Zxxx code, assignable, and closeable through the same workflow as any other security advisory.

The documentation pipeline is now a first-class citizen of your security posture.

The Purity Protocol: Zero Engine Leaks in Core​

One invariant that emerged from the consolidation and defines the v0.7.0 architecture: validator.py — the heart of Zenzic — contains no reference to any engine by name. No "docusaurus", no "sidebar", no "navbar". The Core receives a frozenset[str] of navigable paths from adapter.get_nav_paths(). What lives inside that method is the adapter's problem, not the Core's.

# validator.py — the entire engine interface
nav_paths = adapter.get_nav_paths()   # frozenset[str] | frozenset()

For Docusaurus, get_nav_paths() is a Multi-Source Harvester: it merges sidebar IDs, navbar to: paths, and footer to: paths into a single frozenset before returning it. The Core never sees the difference. For MkDocs, the same method returns nav: entries. For Zensical, it returns nav: entries. For Standalone, it returns frozenset().

One interface. Four adapters. Zero engine leaks in Core.

Adding a new adapter that modifies validator.py is a protocol violation. The adapter contract is the boundary — everything engine-specific must live behind it.

The Zenzic Lab: 20 Acts​

The Lab is the fastest way to understand what Zenzic does. Run it now:

uvx zenzic lab

Twenty interactive Acts, each demonstrating a distinct capability against bundled fixture projects:

No configuration required. No project to set up. The Lab runs against bundled fixture projects — no temporary files, no teardown required. The entire experience runs in under 90 seconds on a cold start.

The Documentation of the Documentation Tool​

One constraint that emerged during the Diátaxis restructure of zenzic.dev: a documentation tool that ships with poorly organised documentation is not a credible authority on documentation quality.

The site now follows the Diátaxis framework across four modes:

• Tutorials — step-by-step learning paths for new users
• How-To Guides — task-oriented instructions for specific problems
• Reference — the complete Zxxx diagnostic registry, CLI interface, and engine specs
• Explanation — the architectural decisions, security model, and design philosophy

Every URL changed in the restructure. The Sovereign Root Protocol found all three README.md links pointing at the old paths before any user reported them. The tool caught its own documentation drift.

Get Started in 30 Seconds​

uvx zenzic lab

No installation required. uvx resolves and runs Zenzic from PyPI in a temporary environment. The Lab will walk you through every capability interactively.

For a permanent installation:

uv add --dev zenzic
# or
pip install zenzic

Then run a check against your documentation:

zenzic check all ./docs

Part 5 of the Zenzic Chronicles. For the complete architectural journey, visit the Safe Harbor Blog.

The 1,525-line Obsidian Masterclass covers every component in depth — verified by 1,485+ tests across Python 3.10 and 3.14.

That promise is architecturally broken. And your documentation is paying the price.

Act I — The Thesis of Untrusted Input​

The Problem with Build Engines​

Your documentation pipeline looks something like this:

Author → Markdown file → Build Engine → HTML → CDN → Reader
                              ↑
                    "Trust me, I'll build it."

Docusaurus, MkDocs, Zensical — these are generators. Their contract with you is explicit: "Give me source files; I will produce a static site." They are optimized for speed, for plugin extensibility, for theming. They are not optimized for validation. They trust the source files you give them.

That trust is the vulnerability.

What "Untrusted Input" Means in 2026​

The threat model for documentation has changed. In 2026, documentation sources come from:

• Human contributors via pull requests — who may not know your link structure
• AI-generated content — which plausibly invents URLs that sound real
• Automated refactors — which move files without updating cross-references
• External integrations — which inject content that may carry credential fragments

In a monorepo shared across teams, a single contributor committing a file that references a non-existent anchor, exposes an internal API key, or introduces a circular link dependency can silently corrupt the documentation of ten product areas simultaneously. The build engine will not catch it. The build engine does not try.

Zenzic's core design thesis, established in ADR-001, is: treat every Markdown file as untrusted input.

This is not a feature. It is a trust model. Every design decision in Zenzic derives from it.

The Zero-Trust Documentation Pipeline​

Author → Markdown file → Zenzic (Sentinel) → Build Engine → HTML → CDN → Reader
                              ↑
                    "I trust nothing. I verify everything."

The Sentinel runs before the build. It does not trust the source. It constructs a complete in-memory model of your site — the Virtual Site Map — and validates every claim in your source files against that model. If the model says a link is broken, the CI gate fails. The build engine never sees the broken file.

The fundamental difference is not in features. It is in philosophy. Build engines are designed to succeed. Zenzic is designed to find where they would have failed.

Supply Chain Attacks via Documentation​

Consider a real scenario: your documentation site is a monorepo including third-party-contributed guides. One contributor submits a tutorial that includes:

## Setup

Configure your environment with your API key:

```yaml

api_key: "sk_live_<YOUR_STRIPE_KEY_HERE>"

The Stripe live key — `sk_live_*` — is a real credential format. Zenzic's Shield
catches it before the commit merges. The build engine builds it without comment.

This is the **supply chain attack surface in documentation**: external content that
carries secrets, adversarial links, or path traversal payloads, combined with a build
pipeline that trusts its input entirely.

Zenzic's response to this is the three-layer security architecture: the **Shield**
(credentials), the **Blood Sentinel** (paths), and the **Structural Validator** (graph
integrity). Each layer is independent. Each layer runs on every scan. None of them
can be disabled simultaneously.

### The Three Pillars (Non-Negotiable)

These invariants are in Zenzic's design contract and cannot be overridden by
configuration:

**Pillar 1 — Lint the Source, Not the Build.** Analysis operates on raw Markdown and
configuration files. Never on HTML output. Errors are caught before the build starts.

**Pillar 2 — Zero Subprocesses.** 100% pure Python. No `subprocess`, no `os.system`,
no Node.js execution. This guarantees: reproducible results across platforms,
zero dependency on the build environment, and total portability.

**Pillar 3 — Pure Functions First.** Analysis logic is deterministic. I/O is isolated
at the edges (discovery and reporting). No I/O in hot-path loops.

---

## Act II — The VSM Engine: A Mental Map of Your Site

### What the Virtual Site Map Is

The Virtual Site Map (VSM) is Zenzic's central data structure. It is a complete
in-memory projection of your documentation site as a routing table: a mapping from
every canonical URL that your build engine would generate to a `Route` object.

The `Route` object carries:

```python
@dataclass(frozen=True, slots=True)
class Route:
    url: str           # canonical URL: "/docs/guide/install/"
    file_path: Path    # absolute path on disk: /repo/docs/guide/install.mdx
    status: RouteStatus
    anchors: frozenset[str]
    is_proxy: bool
    version: str | None

The RouteStatus can be one of four values:

Why the VSM Is Necessary​

Without the VSM, Zenzic could only answer: "does this file exist on disk?" That question is easy. pathlib.Path.exists() answers it in a single syscall.

The VSM enables Zenzic to answer a harder question: "would this link resolve in the rendered site, given how your specific build engine maps source files to URLs?"

Those are completely different questions.

Consider Docusaurus: a file at docs/guide/index.mdx is served at /docs/guide/, not at /docs/guide/index/. A link to /docs/guide/index.html would resolve to nothing in the browser — even though the file exists on disk.

Consider MkDocs: a file at docs/api.md with nav: entry - API: api.md is reachable. The same file without a nav: entry is potentially an orphan depending on nav: configuration.

The VSM encodes these engine-specific routing rules in pure Python, without running the build engine.

Building the VSM: The Architecture​

                        ┌─────────────────────────────┐
                        │        build_vsm()           │
                        │   (I/O boundary — called     │
                        │    once per scan)            │
                        └──────────┬──────────────────┘
                                   │
                    ┌──────────────▼──────────────────┐
                    │       Adapter.get_route_info()   │
                    │  (engine-specific, per-file)     │
                    └──────────────┬──────────────────┘
                                   │
              ┌────────────────────▼────────────────────────┐
              │                                             │
   ┌──────────▼─────────┐  ┌────────────────┐  ┌──────────▼──────────┐
   │  map_url(rel)       │  │ classify_route │  │  get_nav_paths()     │
   │  (canonical URL)    │  │  (reachability)│  │  (sidebar+nav+footer)│
   └────────────────────┘  └────────────────┘  └─────────────────────┘

The build_vsm() function is the only I/O boundary — it iterates over every Markdown file in docs_root exactly once. All adapter calls are pure functions after that initial read. No file is touched again during link validation.

O(1) Link Validation​

The VSM is a Python dict[str, Route] — a hash map keyed by canonical URL.

When the validator needs to check whether a link target exists, it calls:

route = vsm.get(canonical_url)    # dict.get() — O(1) hash lookup
if route is None:
    # Z104: FILE_NOT_FOUND

This means validating 10,000 links against a 10,000-page site is not O(N²) — it is 10,000 independent O(1) lookups. The VSM is built once (O(N)) and then queried indefinitely at O(1) per link.

Compare this to naive implementations that call Path.exists() for every link target: that is N×M syscalls for N links across M files, where each stat() call crosses the user-kernel boundary. At 50,000 links across a large documentation site, the difference between O(1) hash lookups and O(N×M) syscalls is the difference between a 3-second scan and a 90-second scan.

The Anchor Cache​

In addition to the URL map, the VSM builder constructs an anchor cache: a mapping from file path to the set of heading slugs that file declares.

anchors_cache: dict[Path, set[str]] = {
    Path("/repo/docs/guide/install.mdx"): {
        "prerequisites", "installation", "next-steps"
    },
    ...
}

When a link contains a fragment (/docs/guide/install/#next-steps), Zenzic:

1. Resolves the URL to a file path via the VSM (O(1))
2. Checks the fragment against anchors_cache[file_path] (O(1) set lookup)

A broken anchor (Z102) is detected with two hash lookups. Zero I/O. Zero subprocess calls.

Ghost Routes: i18n and Versioning​

The VSM handles cases where a URL exists but no physical file produces it — what Zenzic calls Ghost Routes. Two categories:

i18n Ghost Routes: Docusaurus generates locale-specific index pages (e.g., /it/docs/) automatically, even when no physical it/index.mdx exists. The VSM marks these as is_proxy=True and status=REACHABLE, because the build engine will generate them.

Versioned Routes: Zenzic's Docusaurus adapter uses an internal _version_ sentinel prefix to track versioned documentation trees. A file at docs/versioned_docs/version-0.6/guide.md is indexed as _version_/0.6/guide.md in the VSM and served at /docs/0.6/guide/ — transparent to the validator.

In both cases, the VSM answer is correct: the URL is reachable for a reader. No physical file required.

Collision Detection​

Two source files can produce the same canonical URL — this is a build-time error in Docusaurus and MkDocs. The VSM detects this during construction:

def _detect_collisions(routes: list[Route]) -> None:
    seen: dict[str, Route] = {}
    for route in routes:
        if route.url in seen:
            route.status = "CONFLICT"
            seen[route.url].status = "CONFLICT"
        else:
            seen[route.url] = route

A CONFLICT route surfaces as a Zenzic finding before the build runs, preventing the silent data loss that occurs when two files compete for the same URL.

Act III — The Shield: 8 Stages of Truth​

The Problem with Naive Secret Detection​

A naive credential scanner applies regex patterns line by line:

if re.search(r"AKIA[0-9A-Z]{16}", line):
    flag_secret()

This works when the secret is written plainly. In documentation, secrets are rarely written plainly. They appear in:

• Markdown tables: | Key | `` AKIA`` | ``1234567890ABCDEF `` |
• Concatenated strings: `AKIA` + `1234ABCD5678EFGH`
• HTML-entity encoded values: AKIA1234567890ABCDEF
• Unicode-obfuscated text: A\u200bK\u200bI\u200bA1234567890ABCDEF (zero-width spaces)
• Comment-interleaved tokens: ghp_ABC{/* comment */}DEF
• Cross-line YAML scalars: key split across two lines by a folded block

Zenzic's Shield is designed to defeat all of these patterns. It does so through a normalization pipeline applied before regex matching.

The 8 Stages of Normalization​

The _normalize_line_for_shield() function applies these transformations in strict order:

Stage 1 — Unicode Format Character Stripping (ZRT-006)​

normalized = "".join(c for c in line if unicodedata.category(c) != "Cf")

Unicode category Cf ("Format, other") includes invisible characters: zero-width joiners (U+200D), zero-width non-joiners (U+200C), zero-width spaces (U+200B), and word joiners (U+2060). An adversarial author can insert these between characters of a secret key — the characters are visually invisible and collapse when copy-pasted, but a naive regex will not match the fragmented token.

Stage 1 strips them entirely, reconstructing the original token.

Stage 2 — HTML Character Reference Decoding (ZRT-006)​

normalized = html.unescape(normalized)

HTML character references (A, A, &) can encode any ASCII character. A key like AKIA1234567890ABCD can be written as AKIA1234567890ABCD in inline HTML within a Markdown file — and will render correctly in the browser while evading naive scanners.

html.unescape() from the Python standard library handles all forms: decimal (&#NNN;), hexadecimal (&#xHH;), and named references (&).

Stage 3 — HTML Comment Stripping (ZRT-007)​

_HTML_COMMENT_RE = re.compile(r"<!--.*?-->")
normalized = _HTML_COMMENT_RE.sub("", normalized)

HTML comments can interleave token fragments: ghp_ABC<!-- noise -->DEF. After the build, the comment is invisible. In the source, it splits the token. Stage 3 removes the comment, joining ghp_ABC and DEF into ghp_ABCDEF, which is then matched by the GitHub token pattern on a subsequent pass.

Stage 4 — MDX Comment Stripping (ZRT-007)​

_MDX_COMMENT_RE = re.compile(r"\{/\*.*?\*/\}")
normalized = _MDX_COMMENT_RE.sub("", normalized)

MDX files use JSX-style comments: {/* ... */}. The same interleaving attack applies. Stage 4 handles the MDX-specific variant independently.

Stage 5 — Backtick Code Span Unwrapping (ZRT-003)​

_BACKTICK_INLINE_RE = re.compile(r"`([^`]*)`")
normalized = _BACKTICK_INLINE_RE.sub(r"\1", normalized)

Documentation authors frequently write tokens inside inline code spans for visual formatting: `AKIA`. The backticks are presentation — they do not change the semantics of the content. Stage 5 strips them, exposing the raw token to the regex patterns.

Stage 6 — Concatenation Operator Removal (ZRT-003)​

_CONCAT_OP_RE = re.compile(r"[`'\"\s]*\+[`'\"\s]*")
normalized = _CONCAT_OP_RE.sub("", normalized)

Split-token patterns in documentation tables:

| Field | Value |
|-------|-------|
| Key   | `AKIA` + `1234567890ABCDEF` |

The + operator joined with surrounding backticks is a common representation of string concatenation in documentation. Stage 6 removes the concatenation construct, joining the fragments into AKIA1234567890ABCDEF.

Stage 7 — Table Pipe Replacement​

_TABLE_PIPE_RE = re.compile(r"\|")
normalized = _TABLE_PIPE_RE.sub(" ", normalized)

Markdown table cells are separated by |. A secret split across cells would be: | AKIA | 1234567890ABCDEF |. Stage 7 converts pipes to spaces, enabling whitespace collapse in Stage 8 to produce a scannable line.

Stage 8 — Whitespace Normalization​

return " ".join(normalized.split())

Collapses all whitespace runs (tabs, multiple spaces, newlines) into single spaces. This is the final normalization before regex matching. The result is a clean, compact line where all obfuscation techniques have been defeated.

The Lookback Buffer: Cross-Line Detection​

A secret that spans two lines defeats single-line scanning:

api_key: >-
  AKIA
  IOSFODNN7EXAMPLE

Each line individually contains only a fragment. Neither line matches the AWS access key pattern AKIA[0-9A-Z]{16}.

Zenzic addresses this with scan_lines_with_lookback() — a stateful scanner that maintains a 1-line lookback buffer:

def scan_lines_with_lookback(
    lines: Iterator[tuple[int, str]],
    file_path: Path | str,
) -> Iterator[SecurityFinding]:
    prev_normalized: str = ""
    for line_no, raw_line in lines:
        normalized = _normalize_line_for_shield(raw_line)
        # Scan the cross-line join: tail of previous line + head of current
        cross_line = prev_normalized[-40:] + normalized[:40]
        yield from scan_line_for_secrets(cross_line, file_path, line_no)
        # Scan the current line independently
        yield from scan_line_for_secrets(raw_line, file_path, line_no)
        prev_normalized = normalized

The cross-line join concatenates the last 40 characters of the normalized previous line with the first 40 characters of the normalized current line — enough to reconstruct any secret split across a line boundary, while keeping memory bounded.

Dual-Form Scanning​

Even after normalization, Zenzic scans each line in two forms:

1. Raw form — the line exactly as it appears in the source, ensuring that normally

   formatted secrets are always caught with correct column positions for reporting.

2. Normalized form — after all 8 stages, ensuring that obfuscated secrets are

   reconstructed and matched.

Duplicate findings (same secret type on the same line in both forms) are suppressed via a seen: set[str] de-duplication pass.

ReDoS Prevention: The F2-1 Hardening​

Regex patterns applied to pathological inputs can cause catastrophic backtracking — a ReDoS (Regular Expression Denial of Service) attack. A crafted Markdown file with a megabyte-long line could cause a regex engine to consume unbounded CPU.

Zenzic's F2-1 hardening establishes a maximum line length constant:

_MAX_LINE_LENGTH: int = 1_048_576  # 1 MiB

Lines exceeding this limit are silently truncated before scanning. No secret longer than 1 MiB exists in practice; a line longer than 1 MiB is not legitimate documentation.

Additionally, all regex patterns used in _SECRETS undergo an eager ReDoS pre-flight check at engine construction time (ZRT-002):

def _assert_regex_canary(rule: BaseRule) -> None:
    """Verify that the rule's regex does not exhibit catastrophic backtracking."""
    # Applies a timing canary against a known-adversarial input.
    # Raises PluginContractError if the pattern exceeds the time budget.

Custom rules loaded via the zenzic.rules entry-point group are subject to the same pre-flight check before the first file is scanned.

The 9 Secret Families​

Zenzic's Shield v0.7.0 detects credentials across 9 families:

Each pattern is pre-compiled at import time — zero compilation overhead during scanning. The set is additive: new families are added by appending to the _SECRETS list.

Exit Code 2: The Sacred Exit​

Any detection by the Shield causes Zenzic to exit with code 2. This exit code is non-suppressible — it cannot be silenced by --exit-zero, fail-on-error: false, or any configuration flag.

The rationale: a CI system that can be configured to ignore credential exposure is not a security gate. It is theater. Exit code 2 is the guarantee that the security contract cannot be bypassed by configuration drift or operator error.

Exit 0 — All checks passed
Exit 1 — Quality findings (broken links, orphans, placeholders) — suppressible
Exit 2 — Security breach (Shield: credential detected) — NEVER suppressible
Exit 3 — Fatal breach (Blood Sentinel: path traversal) — NEVER suppressible

The Shield operates in Pass 1A — before any structural analysis. A file that triggers exit 2 does not proceed to link validation or orphan detection. The Sentinel reports the breach and stops.

Act IV — Blood Sentinel: Kernel-Level Sandboxing​

Path Traversal in CI/CD​

In a CI/CD pipeline, Zenzic runs in a containerized runner. The runner has access to:

• SSH keys: /home/runner/.ssh/id_rsa
• System secrets: /etc/passwd, /etc/shadow
• Runner tokens: /var/run/secrets/kubernetes.io/serviceaccount/token

A Markdown file can embed a path traversal attack:

[Evil link](../../../../etc/passwd)
[Another attack](../../../home/runner/.ssh/id_rsa)

A documentation site that renders these files to HTML becomes a vector for exfiltrating runner secrets, depending on the deployment mechanism and how static assets are served.

More critically: Zenzic itself reads file contents to validate them. A path traversal in a link target could cause Zenzic to validate /etc/passwd as a documentation file and include its content in a report. This is the tool-level attack — abusing the validator to read secrets from the runner filesystem.

The Blood Sentinel prevents both categories.

The os.path.normpath Collapse​

The defense is built into InMemoryPathResolver._build_target():

def _build_target(self, source_file: Path, path_part: str) -> str:
    if path_part.startswith("/"):
        raw = self._root_str + os.sep + path_part.lstrip("/")
    elif path_part.startswith("@site/docs/"):
        raw = self._root_str + os.sep + path_part[len("@site/docs/"):]
    elif path_part.startswith("@site/"):
        raw = self._repo_root_str + os.sep + path_part[len("@site/"):]
    else:
        raw = str(source_file.parent) + os.sep + path_part
    return os.path.normpath(raw)  # ← The collapse

os.path.normpath() is pure C string arithmetic — no syscalls, no stat(), no readlink(). It collapses all . and .. segments mathematically.

The result:

source: /repo/docs/guide/install.mdx
link:   ../../../../etc/passwd

raw = /repo/docs/guide/../../../etc/passwd
normpath → /etc/passwd

The target string /etc/passwd is produced before any filesystem call is made. Then the Shield check:

shield_ok = (
    target_str == self._root_str
    or target_str.startswith(self._root_prefix)
)
if not shield_ok:
    return PathTraversal(raw_href=href)

/etc/passwd does not start with /repo/docs/ → PathTraversal returned immediately. Zero filesystem access. Zero data exposure. Exit 3.

The Multi-Root Perimeter​

Zenzic handles multi-locale Docusaurus projects where both docs/ and i18n/it/docusaurus-plugin-content-docs/current/ contain cross-referencing files.

The InMemoryPathResolver constructor accepts an allowed_roots parameter — a list of additional authorized boundaries:

_extra = [self._coerce_path(r) for r in (allowed_roots or [])]
_pairs: list[tuple[str, str]] = []
for _r in [self._root_dir, *_extra]:
    _s = str(_r)
    _pairs.append((_s, _s + os.sep))
self._allowed_root_pairs: tuple[tuple[str, str], ...] = tuple(_pairs)

The Shield check becomes:

shield_ok = any(
    target_str == root_str or target_str.startswith(root_prefix)
    for root_str, root_prefix in self._allowed_root_pairs
)

A relative link from docs/guide.mdx to ../i18n/it/guide.mdx is valid only if i18n/it/docusaurus-plugin-content-docs/current/ is in allowed_roots. Without explicit authorization, it produces PathTraversal. The perimeter is explicitly declared, not inferred.

The @site/ Alias: Security Analysis​

Docusaurus allows @site/ as an alias for the project root in import statements and static asset references. Zenzic maps this alias to repo_root:

elif path_part.startswith("@site/docs/"):
    raw = self._root_str + os.sep + path_part[len("@site/docs/"):]
elif path_part.startswith("@site/"):
    raw = self._repo_root_str + os.sep + path_part[len("@site/"):]

A path like @site/../etc/passwd becomes:

raw = /repo/../etc/passwd
normpath → /etc/passwd

The normpath collapse happens before the perimeter check. @site/ is not an escape hatch from the Blood Sentinel. It is an alias for a specific root, and all .. traversals through it are collapsed and checked identically.

Exit Code 3: Non-Negotiable Termination​

Path traversal findings (Z202/Z203) cause exit 3. Like exit 2, this is non-suppressible. A path traversal in a documentation source is not a quality finding. It is an attempted perimeter breach. The Sentinel terminates.

Z202 PATH_TRAVERSAL — confirmed: resolved path escapes docs_root
Z203 PATH_TRAVERSAL_SUSPICIOUS — unresolvable path with traversal segments

The distinction: Z202 is triggered when normpath produces a path that fails the prefix check. Z203 is triggered when the href contains ../ segments but cannot be fully resolved (e.g., missing fragments, malformed URLs). Both produce exit 3.

Act V — The Docusaurus Adapter: isCategoryIndex and URL Collapsing​

The Routing Problem​

Docusaurus maps source files to URLs through a set of rules that are not always obvious to documentation authors. Zenzic must replicate these rules exactly in Python to produce correct VSM entries.

The most complex rule is isCategoryIndex collapsing: when a file's name matches certain patterns, its URL is collapsed to the parent directory, not a file slug.

The Three Collapsing Cases​

From _docusaurus.py, the collapsing logic:

if parts:
    file_name_lower = parts[-1].lower()
    parent_name_lower = parts[-2].lower() if len(parts) >= 2 else None
    if (
        file_name_lower == "index"          # Case 1: index file
        or file_name_lower == "readme"      # Case 2: README file
        or (
            parent_name_lower is not None
            and file_name_lower == parent_name_lower  # Case 3: folder-match
        )
    ):
        parts = parts[:-1]  # collapse to parent

Case 1 — Index collapse:

docs/guide/index.mdx    →  /docs/guide/
docs/index.mdx          →  /docs/

Case 2 — README collapse:

docs/guide/README.md    →  /docs/guide/
docs/README.md          →  /docs/

Case 3 — Folder-match collapse (isCategoryIndex):

docs/guide/guide.mdx    →  /docs/guide/   (filename == parent dirname)
docs/api/api.md         →  /docs/api/

This third case is frequently surprising to authors: a file named after its parent directory is silently collapsed to the directory URL by Docusaurus. Zenzic replicates this behavior exactly, producing the correct canonical URL in the VSM.

URL Priority: Frontmatter Slug First​

Before filesystem derivation, Zenzic checks for a slug: frontmatter declaration:

# Stage 1: frontmatter slug override
slug = self._slug_map.get(rel_posix)
if slug is not None:
    if slug.startswith("/"):
        # Absolute slug: prefix with routeBasePath
        rbp = self._route_base_path or "docs"
        return "/" + rbp + slug.rstrip("/") + "/"
    else:
        # Relative slug: replace last path segment
        parent = rel.parent
        return "/" + parent.as_posix() + "/" + slug.strip("/") + "/"

The full URL resolution priority:

1. Frontmatter slug: — absolute or relative override
2. isCategoryIndex — index/README/folder-match collapse
3. Extension stripping — .md / .mdx removed
4. routeBasePath prefix — default "docs", configurable

The provides_index() Contract​

The provides_index(directory_path) method determines whether a directory has a landing page — required for the Z401 (MISSING_DIRECTORY_INDEX) check:

def provides_index(self, directory_path: Path) -> bool:
    index_files = ("index.md", "index.mdx", "README.md", "README.mdx")
    if any((directory_path / f).exists() for f in index_files):
        return True
    category_json = directory_path / "_category_.json"
    if category_json.exists():
        data = json.loads(category_json.read_text(encoding="utf-8"))
        link = data.get("link", {})
        return isinstance(link, dict) and link.get("type") == "generated-index"
    return False

A directory provides an index when:

1. An index.md, index.mdx, README.md, or README.mdx exists inside it, or

2. A _category_.json declares "link": { "type": "generated-index" } — causing

   Docusaurus to auto-generate a category index page.

I/O is permitted in provides_index() because it is called once per directory during the discovery phase — never inside per-link or per-file hot loops.

The Three-Surface Harvester​

For orphan detection, Zenzic's Docusaurus adapter aggregates navigation paths from three sources:

def get_nav_paths(self) -> frozenset[str]:
    """Merge sidebar + navbar + footer into a single navigable path set."""
    return (
        self._parse_sidebars()           # sidebars.ts / sidebars.js
        | self._parse_config_navigation() # navbar.items + footer.links
    )

Sidebar parsing (_parse_sidebars()): reads sidebars.ts or sidebars.js via pure-Python regex. Strips JS-style line and block comments before parsing. Handles both type: 'doc' explicit entries and bare string IDs.

Config navigation (_parse_config_navigation()): reads docusaurus.config.ts via regex, extracts to: URL paths from navbar.items and footer.links, strips baseUrl and routeBasePath prefixes, and probes for .md/.mdx files on disk.

A file is ORPHAN_BUT_EXISTING only if absent from sidebar AND navbar AND footer. A changelog linked only in the navbar is REACHABLE. A legal notice linked only in the footer is REACHABLE. This is R21 — UX-Discoverability.

The Slug Law: Physical Consistency​

Zenzic's own documentation enforces the Slug Law (ADR-003): no slug: frontmatter that diverges from the physical file path. The rationale is architectural: the autogenerated sidebar uses type: 'autogenerated' — it resolves URLs from file paths. A diverged slug: creates a URL that the sidebar cannot resolve, causing navigation failures without a build-time error.

The VSM enforces this indirectly: if a slug: produces a URL that no sidebar entry references, the file is ORPHAN_BUT_EXISTING. The Slug Law converts this from a silent failure to a Zenzic finding.

Act VI — The Rule Engine: Adaptive Parallelism​

The AdaptiveRuleEngine​

Custom rules in Zenzic — declared in [[custom_rules]] or implemented as Python classes via the zenzic.rules entry-point group — are applied through the AdaptiveRuleEngine:

class AdaptiveRuleEngine:
    def __init__(self, rules: Sequence[BaseRule]) -> None:
        for rule in rules:
            _assert_pickleable(rule)    # eager pickle validation
            _assert_regex_canary(rule)  # ZRT-002: ReDoS pre-flight
        self._rules = rules

    def run(self, file_path: Path, text: str) -> list[RuleFinding]:
        """Pure function: file path + text → findings. No I/O."""
        findings: list[RuleFinding] = []
        for rule in self._rules:
            try:
                findings.extend(rule.check(file_path, text))
            except Exception as exc:
                # Rule failures are caught and converted to RULE-ENGINE-ERROR findings.
                # One faulty plugin cannot abort the scan of the entire docs tree.
                findings.append(RuleFinding(...))
        return findings

Rules are validated eagerly at construction time, before the first file is scanned. A rule that fails pickle serialization is rejected immediately — not silently inside a worker process during a long parallel scan.

The 50-File Threshold​

Zenzic's scanner switches between sequential and parallel execution based on the number of files:

ADAPTIVE_PARALLEL_THRESHOLD: int = 50  # in scanner.py

use_parallel = workers != 1 and len(md_files) >= ADAPTIVE_PARALLEL_THRESHOLD

Below 50 files: sequential execution. The overhead of spawning a ProcessPoolExecutor — approximately 200–400 ms on a cold interpreter — exceeds the parallelism benefit for small documentation sets.

At or above 50 files: ProcessPoolExecutor is used:

with concurrent.futures.ProcessPoolExecutor(max_workers=actual_workers) as executor:
    futures_map = {
        executor.submit(_worker, item): item[0]
        for item in work_items
    }
    for future in concurrent.futures.as_completed(futures_map):
        results.extend(future.result())

Each file is dispatched to an independent worker process. The worker receives a serialized (file_path, config, rules) tuple via pickle — which is why the eager pickle validation at AdaptiveRuleEngine construction is load-bearing. A non-pickleable lambda in a custom rule would silently fail inside the worker process; the eager check catches it in the main process at startup.

Pure Function Discipline: Why It Matters for Parallelism​

Pillar 3 — Pure Functions First — is not a style preference. It is an architectural requirement for correctness under parallelism.

A rule that holds mutable state between check() calls (e.g., a counter, a cache) would produce data races when two workers process files simultaneously. A rule that makes I/O calls inside check() would suffer from TOCTOU (time-of-check to time-of-use) races in a parallel context.

Pure functions — deterministic, stateless, side-effect-free — are safe to execute concurrently without synchronization. The AdaptiveRuleEngine guarantees this by contract: any rule that cannot be expressed as a pure function cannot satisfy the PluginContractError validation and will not be admitted to the engine.

The Pickle Serialization Check​

Custom rules loaded via entry_points(group="zenzic.rules") are validated with:

def _assert_pickleable(rule: BaseRule) -> None:
    try:
        pickle.dumps(rule)
    except Exception as exc:
        raise PluginContractError(
            f"Rule '{rule.rule_id}' cannot be pickled and is incompatible with "
            f"multiprocessing: {exc}"
        ) from exc

This is an eager contract check: the error is raised before any file is touched, with a clear message pointing to the rule that failed. Without this check, the failure would manifest as a cryptic BrokenPipeError or EOFError inside a worker process at scan time — far harder to diagnose.

Act VII — Enterprise Integration: SARIF and the Quality Gate​

SARIF 2.1.0: Documentation in Your Security Dashboard​

SARIF (Static Analysis Results Interchange Format) is the standard output format for security tools consumed by GitHub Code Scanning, Azure DevOps, and other CI/CD platforms.

Zenzic produces valid SARIF 2.1.0 with:

zenzic check all ./docs --format sarif > zenzic.sarif

The SARIF output includes:

• Tool descriptor with Zenzic version and URI
• Rules array with one entry per Zxxx code found (ID, name, helpUri, severity)
• Results array with location (file + line + column), message, and level

A minimal SARIF result for a broken link:

{
  "ruleId": "Z101",
  "level": "error",
  "message": {
    "text": "Z101 LINK_BROKEN: './install.mdx' → './guide/setup.mdx' does not exist"
  },
  "locations": [{
    "physicalLocation": {
      "artifactLocation": { "uri": "docs/install.mdx" },
      "region": { "startLine": 42, "startColumn": 12 }
    }
  }]
}

Upload to GitHub Code Scanning:

name: Documentation Integrity Gate

on: [push, pull_request]

jobs:
  sentinel:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4

      - name: Run Zenzic Sentinel

        run: uvx zenzic check all ./docs --format sarif > zenzic.sarif

      - name: Upload to GitHub Security

        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: zenzic.sarif
        if: always()   # upload even when Zenzic fails

The if: always() is critical: when Zenzic exits with code 1 (quality findings), the step is marked as failed — but the SARIF upload must still execute to surface the findings in the Security tab. Without if: always(), a failed step would abort before uploading, producing silence instead of visibility.

For teams using zenzic-action:

- uses: PythonWoods/zenzic-action@v1

  with:
    version: "0.7.0"
    format: sarif
    upload-sarif: "true"

The action handles the SARIF upload and the if: always() semantics automatically, including SARIF integrity validation — if the SARIF file is truncated by runner OOM or SIGKILL, the action emits a ::warning annotation rather than uploading a false- clean result (Output-First Semantics, ADR-004 in zenzic-action).

Machine Silence: RULE R20​

When --format sarif or --format json is active, Zenzic enforces Machine Silence (R20): zero Rich banners, headers, or informational panels are written to stdout. The output stream is a machine-readable format and must remain 100% valid against its schema.

This is enforced at the CLI level:

_MACHINE_FORMATS = frozenset({"json", "sarif"})

if output_format not in _MACHINE_FORMATS:
    print_header(console)

A script that pipes zenzic check all --format json | jq '.findings' receives valid JSON with no banner contamination.

The Quality Score: zenzic score​

Beyond binary pass/fail, Zenzic provides a quality score — a 0–100 metric computed from the weighted sum of findings across all check categories:

zenzic score ./docs

The score can be used as a regression gate:

zenzic diff ./docs   # compare current score to last snapshot

diff compares the current scan result against a stored snapshot (zenzic.snapshot.json in the repo root). A score regression (e.g., score drops from 97 to 91) causes a non-zero exit, enabling CI to block merges that degrade documentation quality.

This is the Quality Gate pattern: not a binary pass/fail, but a tracked trend with a configurable failure threshold (fail_under in zenzic.toml).

The Diagnostic Code Registry: Zxxx​

Every Zenzic finding carries a Zxxx code from core/codes.py — the single source of truth for the diagnostic registry.

The full registry by category:

The codes are stable across versions. A CI system that filters findings by Z201 (credentials) can do so independently of Zenzic version bumps. The codes are the documented API surface for tooling integration.

Act VIII — Performance: The Numbers​

The Adaptive Parallelism Benchmark​

The 50-file threshold is a conservative heuristic derived from empirical measurement:

Measurements on a 4-core runner, cold start. Custom rules with moderate complexity.

The ~380 ms fixed overhead of ProcessPoolExecutor spawn is the reason the threshold is not set lower. A threshold of 10 files would cause sequential scans of small repos to pay the spawn cost without benefit.

VSM Construction vs Link Validation​

The scan time breakdown for a 1,000-file project:

Discovery (walk + read):   ~450 ms   (I/O bound — disk sequential)
VSM construction:          ~120 ms   (CPU bound — adapter URL mapping)
Anchor cache build:         ~80 ms   (CPU bound — heading slug extraction)
Link validation:            ~95 ms   (CPU bound — 50,000 hash lookups)
Orphan detection:           ~35 ms   (CPU bound — frozenset intersection)
Shield scan:               ~210 ms   (CPU bound — regex over 1M lines)
Report rendering:           ~40 ms   (CPU bound — Rich formatting)
─────────────────────────────────────
Total:                    ~1,030 ms

:::note Benchmark conditions These figures are for synthetic Markdown files (minimal frontmatter, no JSX, ~10 lines of prose). Real-world MDX files with frontmatter, JSX components, tables, and dense link graphs cost significantly more per file. Measured against the real zenzic-doc project (59 MDX pages): ~7 ms/file vs ~0.5 ms/file for synthetic files. Run python scripts/benchmark.py --repo <path> to measure your own project. :::

Link validation at 50,000 links takes 95 ms — less than the report rendering phase. This is the O(1) hash map in practice: 50,000 dict.get() calls at ~1.9 µs each.

Memory Profile​

The VSM for a 10,000-file project:

Route objects:    10,000 × ~280 bytes  =   ~2.8 MB
Anchor cache:     10,000 × ~1,200 bytes = ~12.0 MB
md_contents:      10,000 × ~8,000 bytes = ~80.0 MB
─────────────────────────────────────────────────
Total RSS:                               ~95 MB

The dominant cost is md_contents — the raw Markdown text held in memory for the Shield scan. Zenzic holds all files in memory simultaneously to avoid repeated I/O during multi-pass analysis. For projects above 50,000 files, a chunked processing mode is planned for a future release.

Cross-Platform CI Matrix​

Zenzic's test suite runs a 3×3 platform matrix on every commit:

OS:     [ubuntu-latest, windows-latest, macos-latest]
Python: [3.11,          3.12,          3.13         ]

9 parallel CI jobs. All 1,342+ tests must pass on all 9 combinations. This is the portability guarantee: Zenzic's output is identical across all platforms. A scan that passes on Ubuntu passes on macOS and Windows — critical for teams using heterogeneous development environments.

Act IX — The Adapter Contract: Extending Zenzic​

The BaseAdapter Protocol​

Zenzic's Core (validator.py, scanner.py) contains zero engine-name references. This is Purity Protocol — Rule R21 (Protocol Sovereignty). Any engine-specific behavior must be declared via the AdapterProtocol and queried by the Core.

The adapter protocol (simplified):

class AdapterProtocol(Protocol):
    def get_nav_paths(self) -> frozenset[str]:
        """Return navigable paths from all user-clickable surfaces."""
        ...

    def map_url(self, rel: Path) -> str:
        """Map a source file to its canonical URL."""
        ...

    def classify_route(self, rel: Path, nav_paths: frozenset[str]) -> RouteStatus:
        """Classify a route as REACHABLE, ORPHAN_BUT_EXISTING, IGNORED, or CONFLICT."""
        ...

    def provides_index(self, directory_path: Path) -> bool:
        """True when the directory will have a landing page."""
        ...

    def get_metadata_files(self) -> list[Path]:
        """Return Level 1 System Guardrail files (excluded from all checks)."""
        ...

    def get_link_scheme_bypasses(self) -> frozenset[str]:
        """Return URI schemes that bypass Z105 absolute-path validation."""
        ...

The Core calls adapter.get_nav_paths(). It receives a frozenset[str]. What generated that frozenset — whether it came from sidebars.ts, mkdocs.yml, or zensical.toml — is invisible to the Core.

Adding a new adapter requires implementing this protocol. Adding an engine-specific behavior by modifying validator.py is a protocol violation and will be rejected in code review.

The pathname:/// Bypass (Rule R16)​

Docusaurus uses pathname:/// as a Diplomatic Courier — an escape hatch for linking to static assets that are not part of the docs routing system:

[Download PDF](pathname:///assets/whitepaper.pdf)

The Z105 gate (ABSOLUTE_PATH) normally fires on any path starting with /. The pathname:/// URI scheme is exempt in Docusaurus mode:

def get_link_scheme_bypasses(self) -> frozenset[str]:
    return frozenset({"pathname"})

The Core queries adapter.get_link_scheme_bypasses() before applying Z105. This is R16 — Protocol Awareness — in action: engine-specific behavior declared in the adapter, queried by the Core, with no if engine == "docusaurus" in Core logic.

In all other engines (MkDocs, Zensical, Standalone), pathname:/// is unrecognized and triggers Z105 normally. The bypass is scoped precisely.

Level 1 System Guardrails​

Adapter metadata files — docusaurus.config.ts, mkdocs.yml, zensical.toml, package.json, pyproject.toml — are declared as Level 1 System Guardrails via get_metadata_files(). These files are:

• Permanently excluded from Z903 (UNUSED_ASSET) checks
• Permanently excluded from all quality checks
• Never presented to the user as orphans, placeholders, or short-content warnings

The rationale (Rule R13 — Intelligent Perimeter): asking the user to manually exclude their own build configuration files from analysis is a failure of the tool, not a configuration task. The adapter knows what its metadata files are; the Core does not need to be told.

Act X — Getting Started​

Immediate Verification (No Installation)​

uvx zenzic lab

uvx resolves the latest Zenzic from PyPI, installs it in an isolated temporary environment, and runs the interactive Lab. Seventeen Acts, each demonstrating a distinct capability. The entire experience requires no project setup.

Start with Act 3 — the Shield in action against a planted Stripe live key. Watch the Sentinel exit with code 2. That exit code is the promise.

Your First Scan​

uvx zenzic check all ./docs

Zenzic will:

1. Discover your documentation engine (Docusaurus, MkDocs, Zensical, or Standalone)
2. Build the VSM from your source files
3. Run the Shield across every line of every file
4. Validate all internal links against the VSM
5. Detect orphan pages via R21 (navbar + sidebar + footer analysis)
6. Report all findings with Zxxx codes, file paths, and line numbers

On a 100-page Docusaurus site: expect 2–4 seconds, cold start.

Pinned CI Integration​

name: Documentation Integrity Gate

on:
  push:
    branches: [main]
  pull_request:

jobs:
  sentinel:
    runs-on: ubuntu-latest
    permissions:
      security-events: write  # required for SARIF upload
    steps:

      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v5

      - uses: PythonWoods/zenzic-action@v1

        with:
          version: "0.7.0"   # pinned — deterministic CI gate
          format: sarif
          upload-sarif: "true"

Version pinning (version: "0.7.0") is mandatory for production pipelines. latest is appropriate for exploration; it introduces non-determinism into your CI gate.

zenzic.toml Configuration​

docs_dir   = "docs"
fail_under = 95        # quality score gate: fail if score drops below 95

# Excluded external URLs (temporary — remove after deployment)
excluded_external_urls = [
  "https://internal.corp.example.com/api",
]

# Excluded asset patterns (Docusaurus sidebar metadata)
excluded_assets = [
  "**/_category_.json",
]

[build_context]
engine         = "docusaurus"
base_url       = "/"
default_locale = "en"
locales        = ["it", "fr"]

The 4-level configuration priority: CLI flags > zenzic.toml > pyproject.toml [tool.zenzic] > built-in defaults. CLI flags always win. This allows temporary overrides without modifying project configuration.

Standalone Mode​

For projects with no build system — raw Markdown directories, GitHub wikis, plain doc trees:

docs_dir = "."

[build_context]
engine = "standalone"

In Standalone mode:

• Orphan detection (Z402) is disabled — there is no navigation contract
• Link validation still runs — broken links are broken regardless of engine
• The Shield still runs — credentials are credentials regardless of engine
• The Blood Sentinel still runs — path traversal is path traversal regardless of engine

The security guarantees are engine-independent. Only the navigation contract is scoped.

Brand Integrity: Z905 BRAND_OBSOLESCENCE​

The fourth dimension of the Safe Harbor — beyond structural, security, and content correctness — is narrative integrity. A documentation suite that refers to a deprecated release codename has a different class of bug: it tells the wrong story.

Configure [project_metadata] in zenzic.toml to activate the Brand Integrity layer:

[project_metadata]
release_name = "Quartz"
obsolete_names = ["Obsidian"]
obsolete_names_exclude_patterns = ["CHANGELOG*.md", "adr-*.mdx"]

The zenzic:ignore Z905 escape hatch is precise by design: it applies to a single line, not a whole file. A CHANGELOG entry that says "Released under the Obsidian codename" is historical fact. An architecture page that describes the current system as "Obsidian-based" is a lie that the source code has already corrected.

Epilogue: The Documentation is the Source​

The engineering tradition treats documentation as secondary — a description of the system, not the system itself. This tradition is breaking down.

In 2026, documentation is:

• The primary interface for internal APIs in large organizations
• The trust signal that developers use to evaluate whether a library is maintained
• The compliance artifact that auditors examine in regulated industries
• The attack surface that adversaries probe for exposed credentials and path traversal

A documentation pipeline that trusts its input is not a pipeline. It is a hope.

Zenzic exists because the question "is this documentation correct?" is not the same question as "did this build succeed?" A build that succeeds on broken documentation has not validated anything. It has just run faster.

The Safe Harbor is not a metaphor. It is an architectural guarantee: every file that passes Zenzic's three layers — the Structural Validator, the Shield, and the Blood Sentinel — has been verified against the navigation contract of your specific build engine, scanned for all known credential formats with 8-stage normalization, and checked for path traversal against an explicitly declared perimeter.

That is the promise. Every exit-0 scan is the proof.

For the full engineering history of how these layers were designed, tested under AI-generated siege, and hardened across five sprints — read the 🛡️ The Zenzic Chronicles →.

Software does not die when its code grows old.

It dies when the pact between the author and the user is broken — the implicit promise that what works today will still make sense tomorrow, that the rules of the game will not shift mid-journey, that the tool you trusted will not become the problem you need to escape.

This is the sixth chronicle. The one we were always building toward.

Part I — The Ghost of Broken Promises​

There is a ghost that haunts mature software projects. Engineers rarely name it, because naming it requires admitting that the problem is not technical. The ghost is not a bug. It is not a performance regression. It is not a security vulnerability.

The ghost is a broken promise.

The Zenzic Chronicles began with a broken promise. Saga I documented the credential that leaked through a MkDocs pipeline — not because the build tool failed, but because the integration model between Zenzic and MkDocs had created a hidden assumption: that Zenzic would run as part of the build, and therefore its security guarantees were only valid when the build executed cleanly.

This is a ghost assumption. It lives in the architecture. It survives refactors. It outlasts the engineer who introduced it. And it only becomes visible when someone asks, at the wrong moment: "what exactly did we promise?"

The Instability at the Foundation​

Saga II documented a second failure mode: Docusaurus link resolution instability when the site was deployed in subdirectory configurations. Links that worked locally failed in production. The build succeeded. The Shield found nothing. The links were broken.

Both failures share a structural cause: the tool was integrated into the build system instead of guarding the source before it. When Zenzic runs inside the build, it inherits all of the build system's assumptions. Its guarantees become conditional. "The analysis is clean" becomes "the analysis is clean, given the following 17 implicit preconditions about your deployment environment."

That is not a guarantee. That is a disclaimer.

The Software Mortality Table​

Projects die in predictable ways. Not from catastrophic failure — from erosion. From the accumulation of reasonable exceptions, each of which makes perfect local sense.

The pattern is not ignorance. The engineers who make these decisions are intelligent. They are making rational local optimizations. The problem is that there is no system that forces the global cost of each local exception to be visible before it is committed.

Governance is that system.

The Architecture of Trust​

Trust in a software tool is not built from documentation. It is built from demonstrated constraints. A tool that could violate your expectations at any moment provides no safety — only the appearance of it.

The difference between a policy and a law is enforcement. Zenzic can write any policy document it wants and ignore it entirely. But a constitutional process — one that requires a major version bump, a 30-day public period, and documented adversarial validation before any Pillar can change — is a constraint that costs something to violate. That cost is what transforms a design principle into an architectural guarantee.

"The ghost is not a bug in the code. It is a promise forgotten — made when the design was pure, abandoned when the pressure was real, invisible until the day the user discovers that what was promised and what was delivered have quietly diverged."

The Governance of Glass is the formal answer to the ghost. Not a process for slowing things down. A process for ensuring that every exception, every evolution, every architectural change is made with full awareness of its cost to the pact.

Part II — The Sovereignty Oath: Liberty as a Feature​

The most unusual document in Zenzic's Governance section is the Sovereignty Oath.

It is a formal document explaining how to remove Zenzic from your project.

We wrote it during the foundational design phase. We wrote it before v0.7.0 was stable. We wrote it because we believe that a tool that cannot prove its own reversibility is asking you to trust it on faith — and the Zenzic trust model is Zero-Trust, including toward Zenzic itself.

The Zero Residue Guarantee​

Zenzic is the only dependency that swears to be invisible if you decide to remove it.

This is not marketing copy. It is a verifiable engineering claim. When you remove Zenzic from a project, the following components remain unchanged:

Total decommission time: 30 seconds. No migration script. No data format to convert. No architecture to dismantle. No vendor lock-in to escape.

Read-Only by Constitution​

The audit core of Zenzic is strictly read-only. This is not a current implementation detail awaiting refactoring. It is a constitutional invariant of the Safe Harbor.

# The Zenzic analysis core: observation only
# Source files are opened in read mode. Always. Without exception
def analyze(file_path: Path, text: str) -> list[Finding]:
    ...  # Pure function. Same input → same output. No writes. No side effects.

Zenzic observes your documentation. It never mutates it.

Any future remediation features — such as a zenzic fix command — will be implemented as separate, explicit, interactive utilities that the user invokes deliberately. The analysis phase will remain 100% mutation-free.

This distinction matters. A linter that quietly "fixes" files during analysis has crossed from observer to actor. The moment a tool modifies your sources without explicit instruction, it becomes the source of unintended mutations — the very class of failure the Safe Harbor was designed to prevent.

The Structural Subtyping Guarantee​

Zenzic's adapter system uses typing.Protocol — the structural subtyping mechanism from the Python standard library.

# Zenzic adapter contract — structural, not nominal
class AdapterProtocol(Protocol):
    def get_docs_root(self) -> Path: ...
    def get_nav_paths(self) -> frozenset[str]: ...
    def get_metadata_files(self) -> frozenset[str]: ...

What this means in practice: your code never inherits from a Zenzic base class. There is no ZenzicAdapter in your class hierarchy. When you remove Zenzic from your project, your Python types are structurally identical to what they were before. The adapter contract is a lens through which Zenzic reads your project — not a chain that binds your types to its release cycle.

Why We Wrote the Exit Strategy First​

A tool that makes leaving difficult does not have confidence in its value. It is protecting its own presence. The conventional wisdom in developer tooling is that switching costs are a moat — friction that keeps users from choosing a competitor.

Zenzic inverts this model. The Zero Residue guarantee is not a concession to user demands. It is a design principle: we believe that tools should be adopted on merit, not retained by friction.

If Zenzic stops providing value — if a better tool emerges, if your documentation stack changes, if your security requirements evolve beyond what Zenzic can deliver — your exit should cost 30 seconds of your life, not 30 days of migration work.

The pact we make with every user is simple and non-negotiable: the Sentinel exists to protect your documentation, not to protect itself.

Part III — The Adversarial Forge: AI as a Skeptic​

The AI-Adversarial / Human-Governed badge is a declaration. Let us be precise about what it declares.

It does not declare that Zenzic was written with AI assistance. It does not declare that AI was used to accelerate development. It declares something more specific — and more demanding.

Zenzic was stress-tested by AI acting as a public prosecutor. Every line of code is a defendant.

The Magistrate Model​

In the Adversarial Forge, AI is assigned the role of a magistrate tasked with building a case for the prosecution. The charge is always the same: "Violation of the Three Pillars."

The AI's job is not to suggest code. Its job is to find a path through the existing architecture that bypasses a constitutional invariant. A working bypass is not a feature request — it is a finding. It is treated with the same urgency as a CVE.

The human's job is not to accept the AI's suggestions. It is to evaluate each finding: Is this a real vulnerability? Does it expose a genuine architectural weakness? If yes, fix it in the same sprint and document it in the Zenzic Ledger. If not, record the unsuccessful attack vector as evidence that the invariant held under adversarial pressure.

The AI proposes. The AI attacks. The AI does not ratify.

When an AI session produces a suggestion to relax a Pillar — "this rule would be much simpler to implement with a subprocess call" — that suggestion is not evaluated on its technical merits in isolation. It is flagged as evidence that the Pillar is under pressure. The response is to harden the invariant documentation, not to accept the suggestion.

The Four Sessions of the Forge​

Every architectural decision in Zenzic has been subjected to one or more of four adversarial session types:

Every "success" for the AI is a failure for Zenzic — a finding that gets fixed before the next release. Every unsuccessful session is documented as evidence that the defense held under real adversarial pressure. The Zenzic Ledger records both outcomes with equal rigor.

Quartz Clarity: Pure Under Pressure​

The metaphor of "Quartz Clarity" is not decorative. Quartz forms under geological pressure rock is cooled rapidly under extreme pressure. Its crystalline structure is the result of having been tested at its limits.

The Eight normalization stages of the Shield — Unicode normalization, HTML entity decoding, invisible character stripping, base64 fragment detection, URL encoding expansion, homoglyph substitution, case folding, whitespace collapse — did not emerge from architectural planning alone. They emerged from successive Type C sessions in which an AI was tasked with constructing credential-containing Markdown fragments that could bypass detection at each stage.

Stage 1 stopped naive plaintext attacks. Stage 3 stopped Unicode codepoint tricks. Stage 6 was added after an AI constructed a homoglyph-substituted token that survived stages 1 through 5. Stage 8 was added after a whitespace collapse bypass was found that survived stages 1 through 7.

"The Shield has eight stages because eight attacks were found and survived. Every stage is the crystallized memory of a bypass attempt that reached production-ready code before being caught by the Forge."

This is Quartz Clarity: not a design reviewed in theory, but a structure tested under the actual force of adversarial intelligence. Its clarity comes from its history of pressure.

What AI Does Not Decide​

The AI is a Red Team, not a co-architect. It operates within strict boundaries:

Part IV — The Constitutional Invariants​

After six Chronicles, after thousands of test cases, after dozens of adversarial sessions, the Three Pillars have been promoted. They are no longer design choices. They are Constitutional Law.

This is not rhetorical elevation. It has a precise engineering meaning: a process exists that makes violating them more expensive than defending them.

The Three Articles of the Safe Harbor​

The Constitutional Amendment Process​

A change that violates any of these articles — even temporarily, even for a genuinely good engineering reason, even under deadline pressure — is not a bug fix or a feature. It is a constitutional amendment. And constitutional amendments in Zenzic require:

1. A Major version increment — e.g., v0.7.0 → v1.0.0. Users who depend on the current

   Pillar semantics remain on the current major version. The change cannot sneak into a minor or patch release.

2. A 30-day public impact period — announced in a public issue before any code is written.

   The period exists so that enterprise users can evaluate the impact on their pipelines, not to create bureaucratic delay.

3. A formal Architectural Decision Record (ADR) — added to the Zenzic Ledger with: the

   text of the invariant being modified, the proposed replacement, the rationale, and a full cost analysis covering migration burden and trust model impact.

4. A Type A Adversarial AI session — targeting the proposed replacement architecture. The

   AI must attempt to find Pillar violations in the new design before it is ratified. A replacement architecture that cannot survive a single adversarial session does not replace a constitutional article.

5. Consensus of 2/3 of Core Maintainers — not a simple majority. Constitutional changes

   require supermajority ratification.

The Evolution Policy: No Surprises at Scale​

The Evolution Policy exists to answer one question that every engineering team eventually asks when adopting an external tool:

"Will the rules of this tool change in a way that breaks our pipeline without warning?"

For most tools, the honest answer is: "Probably. Check the changelog."

For Zenzic, the answer is: "Not without telling you 30 days in advance, not without a major version bump, and not without an adversarial session that proves the replacement architecture can hold under pressure."

This is the enterprise guarantee. Not a feature list. A constitutional process that ensures the Safe Harbor's fundamental rules do not change mid-journey.

What Can Evolve Without Amendment​

Not everything in Zenzic requires a constitutional process to change. The Evolution Policy distinguishes between two tracks:

Lightweight Track (Operational Standards):

Quality gate thresholds, finding code messages (not semantic scope), CLI flag defaults, output format improvements, new adapters, new Zxxx finding codes in unused ranges — these evolve on a 72-hour discussion window with a maintainer merge if no blocking objection is raised. The Zenzic Ledger is updated in the same commit.

Constitutional Track (Pillar-Level):

Anything that changes the meaning of a Pillar — what it protects, what it permits, what it prohibits. These require the full five-step process described above.

The Convenience Prohibition​

The Evolution Policy contains one section that deserves explicit attention: the list of arguments that are formally invalid as rationales for a Pillar amendment.

• "It would be much easier to write this rule with a subprocess call."
• "The AI suggested a simpler architecture that relaxes Pillar III."
• "This is a temporary exception — we'll remove it after the deadline."
• "The test coverage makes this safe even without the invariant."
• "No user has complained about this Pillar being too strict."

None of these arguments are evaluated on their engineering merits. They are rejected because they are convenience arguments — and convenience is precisely the force that the Three Pillars were designed to resist.

"The Pillars are not obstacles to good engineering. They ARE good engineering, expressed as constitutional constraints. The moment they become negotiable for convenience, they cease to protect anything — including the users who trusted them."

Part V — The Safe Harbor is Permanent​

With the publication of this Governance section, Zenzic v0.7.0 crosses a threshold that has nothing to do with features, benchmark numbers, or code coverage percentages.

It has become a documented institution.

The First Cornerstone​

Version 0.7.0 is not a destination. It is the laying of the first cornerstone of a structure designed to stand for decades. The code will evolve. New adapters will be added. New finding codes will be discovered and registered. The CLI will gain new commands. The Shield's normalization stages may be extended by future adversarial sessions that find bypass vectors we have not yet imagined.

None of this threatens the Safe Harbor. The Three Pillars will hold. The Sovereignty Oath will remain in force. The AI adversarial sessions will continue. The Zenzic Ledger will record every decision, every exception, every failure.

This is the promise of the constitutional layer: the rules of the game are public, formal, and non-negotiable at the foundational level. Everything built on top of those foundations can evolve freely — because the foundations themselves are anchored.

The Pact with the Community​

There is a temptation, in open-source governance, to ask users to trust the maintainers. "Trust us, we have good intentions. Trust us, we take security seriously. Trust us, we won't break your pipeline."

We reject this framing entirely.

Do not trust us. Trust the system.

The Governance section is not a statement of our intentions. It is a legal code — a set of invariants and processes that constrain what we can do, even if our intentions were to change. The constitutional amendment process does not require our goodwill to function. It requires a public vote, a 30-day notice period, and documented adversarial validation. These requirements exist regardless of who the maintainers are, what their intentions are, or what pressures they face.

If we ever attempt to modify a Pillar without following that process — file an issue. You will be correct. The Governance system will have been violated. And the community's response to that violation is the final layer of protection the Governance of Glass provides.

The Sentinel Seal: Six Chronicles, One Pact​

The Zenzic Chronicles are sealed.

Six chapters. From the leaking credential in a MkDocs integration to the constitutional layer of a governance-complete open-source project. From a single Shield rule to eight normalization stages tested by adversarial AI. From an integration plugin that blurred the line between "analysis" and "build" to a Sovereign CLI that analyzes any documentation source without depending on its build system.

The Chronicles are a record, not a roadmap. The next chapters of Zenzic's story will be written by the engineers who adopt it, the vulnerabilities that future adversarial sessions will find, the community that will eventually file the first formal RFC under the Evolution Policy, and the enterprise teams who will discover that a 30-second decommission is a feature they never thought to ask for.

"The Safe Harbor is permanent not because it cannot change, but because the process for changing it is more demanding than the pressure to change it casually. That is the only kind of permanence that engineering can honestly offer."

We are ready for the next chapter.

The Glass Constitution​

"Governance of Glass" is a deliberate metaphor.

Glass is not weak. It is transparent. You can see through it. You can verify that what is inside matches what is promised outside. It does not hide its structure behind opacity. When glass breaks, the break is visible — you know exactly where it failed, how it failed, and what force was required to break it.

The Governance documents are glass walls around the Three Pillars. Transparent, verifiable, and brittle under the right kind of force — and that brittleness is the point. A constitution that bends to every reasonable argument is not a constitution. It is a suggestion with aspirational language.

Zenzic's constitution breaks rather than bends. If a Pillar is ever violated without following the constitutional amendment process, the failure is immediately visible: the Zenzic Ledger does not record it, the major version bump did not happen, the 30-day public period did not occur. The violation is auditable from the git history. There are no hidden exceptions.

"Quartz forms under geological pressure — atoms arranged with mathematical precision into a material so sharp it was used as a surgical tool for thousands of years. Its clarity is the product of its history. Zenzic aims to be the same: clear enough to cut through ambiguity, hard enough to maintain its edge under sustained pressure."

The Legal Code of the Sentinel​

The complete constitutional layer is documented at:

Governance & Sovereignty →

"The code is the machine. The governance is the conscience of the machine. One without the other is power without accountability."

The siege is over. All four bypass vectors are closed. 1,195 tests pass. The Bastion holds.

And then we found another bug.

That is how software works. The question is not whether you'll find gaps after a major hardening effort — you will. The question is whether your process catches them before your users do, and whether you have the institutional discipline to close them without inflation.

This is the story of what happened in the final days of high-intensity consolidation leading to v0.7.0, and why the version number itself carries meaning.

Treating Documentation as Untrusted Input​

In application security, the foundational discipline is: never trust input. Passwords are hashed, not stored. Filenames are validated before they touch the filesystem. URLs are parsed and normalised — never concatenated from fragments. The moment you trust your inputs, you have implicitly transferred control to whoever provides them.

Documentation pipelines operate under the opposite assumption. Links are "probably fine." Asset paths are "probably correct." Placeholder values are "probably temporary." The result is exactly what you expect from systems that trust their inputs: slow, silent rot that surfaces as broken experiences for readers — days or even hours after the damage was done.

Zenzic's thesis is that documentation is input, and should be treated with the same skepticism. The Zxxx diagnostic system is input validation. The Shield scanner is a credential sanitiser. The Z502 frontmatter leak fix is a parser boundary constraint. The Z105 pathname:/// false-positive fix is protocol normalisation. Each one applies a discipline that security engineers have practised for decades to a domain that has, until now, operated on optimism.

That transfer of security thinking to documentation quality is what Quartz Maturity actually means.

The Arc: From Sentinel to Maturity​

The Zenzic Engineering Series has documented a continuous thread:

The version jump from v0.6.1 to v0.7.0 was not about features. It was about something more specific: the deliberate rejection of a framing.

Why Not v0.6.2​

After the siege postmortem closed all four bypass vectors, the natural next step was a v0.6.2 patch release. The Zensical and MkDocs adapters needed Z404 coverage. The i18n configuration had a silent fallback bug. The navigation badge hadn't been updated in the bump script. These felt like small fixes.

They weren't small. They were the difference between a system that claims to be a multi-engine Safe Harbor and a system that actually is one.

Z404 (CONFIG_ASSET_MISSING) was originally implemented as Docusaurus-only — a direct contradiction of the engine-agnostic architecture Zenzic was built around. A tool that detects broken favicon references only in Docusaurus projects is not an agnostic tool. It is a Docusaurus tool with MkDocs support bolted on.

The i18n silent fallback was worse. For months, the Italian locale of zenzic.dev was silently serving English content. The URL changed. The content didn't. The bug was in docusaurus.config.ts — htmlLang: 'it-IT' without an explicit path: 'it' caused Docusaurus to look for translations in i18n/it-IT/ (which doesn't exist) and fall back silently to English. The Italian documentation was invisible.

These are not patch-level problems. They are foundational consistency failures in a tool built around the premise that documentation quality is measurable and enforceable.

The Quartz Mirror Audit​

The final pre-release audit — internally called the Quartz Mirror Pass — was structured around a simple question: does every claim Zenzic makes about itself hold when verified against the actual state of the codebase, the documentation, and the published site?

The audit found:

Z404 engine gap. The finding code existed. The implementation was Docusaurus-only. MkDocs theme.favicon and theme.logo were not checked. Zensical [project].favicon and [project].logo were not checked. The fix added check_config_assets() to both _mkdocs.py and _zensical.py, and unified the CLI dispatch to cover all three engines. Lab Acts 9 and 10 were added to demonstrate the fix.

i18n silent fallback. Diagnosed via .docusaurus/i18n.json — the translate: false flag confirmed the Italian locale was not being discovered. Fix: add path: 'it' explicitly to localeConfigs. Documented as institutional memory in the README and the FAQ (EN + IT). Added to the PR checklist.

Navbar badge drift. The version bump script correctly updated the footer and package metadata but missed the >v{version}< HTML badge in the navbar. v0.6.2 persisted in the navbar after the v0.7.0 bump. Fixed in the bump script.

Documentation structure drift (Diátaxis restructure). The documentation portal was restructured following the Diátaxis framework — four clear modes: Tutorials, How-To Guides, Reference, and Explanation. Every section URL changed: /docs/usage/ → /docs/how-to/, /docs/guides/ → /docs/how-to/, /docs/internals/architecture-overview/ → /docs/explanation/architecture/. Three links in README.md had been silently pointing at the old paths for several intensive sprints behind a blanket zenzic.dev exclusion bypass. When the exclusion was removed as part of the perimeter audit, Zenzic flagged all three immediately. The tool caught its own documentation drift.

"True Stable" framing rejected. Early drafts of the release notes used the phrase "True Stable" to describe v0.7.0. The phrase was removed. Stability is not a declaration — it is an ongoing epistemic posture. Calling a release "True Stable" implies that previous releases were somehow dishonestly stable, and that future work won't find gaps. Both implications are false. The correct framing: v0.7.0 is Quartz Maturity — a point of consolidation, not an arrival.

What v0.7.0 Actually Is​

zenzic check all

That command now works correctly against four engine types, with:

The engine-agnostic claim is now verifiable, not aspirational.

The Diagnostic Standard: Zxxx Codes​

The Zxxx code scheme was introduced as a breaking change in v0.6.1 and is the established standard in v0.7.0: every diagnostic emitted by Zenzic carries a machine-readable identifier. No raw string codes. No silent findings. Every problem is named, categorised, and traceable.

The registry lives in src/zenzic/core/codes.py — the single source of truth. Adding a diagnostic without registering its code is a protocol violation. This is what enterprise-grade means in practice: every finding is traceable, filterable, and auditable across releases.

The Vanilla-to-Standalone Sunset​

This release also completes the engine = "vanilla" → engine = "standalone" migration. The migration guard in _factory.py that raises ConfigurationError [Z000] with a clear remediation message was originally annotated # TODO: Remove this migration guard in v0.7.0, implying it was temporary scaffolding. That annotation was wrong. The guard is intentionally permanent: engine = "vanilla" is removed and will never return, so the error message that tells users exactly how to migrate is load-bearing, not transitional. The TODO was removed. The guard stays.

"Standalone Mode" is the canonical identity for documentation projects without a declared build system. It is not a fallback. It is not a default. It is a first-class engine mode with its own adapter, its own Lab Act, and its own documentation.

This release also closes the chapter on the MkDocs plugin dependency that preceded the Headless Architecture. The CLI is now the Sovereign authority: zenzic check all is the single, non-negotiable entry point regardless of what build system the documentation uses. There is no plugin shim. There is no parallel execution path. One command. One verdict.

The Institutional Memory Protocol​

One pattern that emerged clearly during the Quartz Mirror audit: the gap between what the tooling enforces and what the team remembers is where the worst bugs live.

The i18n silent fallback had been present for months. The navbar badge drift had been present since the v0.7.0 bump. Neither was caught by the existing test suite because neither was tested — they were assumed.

The fix was not just to close the bugs. It was to encode the knowledge:

• The i18n trap is now in the README troubleshooting section, the PR checklist, and the

  FAQ (English and Italian).

• The bump script gap is documented in the script itself and the checklist.

• The Structural Map (our deterministic engineering ledger) carries the full sprint history,

  including the root cause, the fix, and the lesson.

A process that catches bugs is valuable. A process that prevents the same bug from recurring is more valuable. The institutional memory protocol is how you get from the first to the second.

The Parity Sprint: When Coverage IS the Audit​

Two days after the initial v0.7.0 write-up, a second forensic sprint surfaced failures that the test suite had not seen — not because the tests were wrong, but because entire modules were untested.

cache.py — zero coverage. The content-addressable finding cache (284 lines) had no test file. Pure hash functions, CacheManager roundtrips, atomic save, parent-directory creation, corrupt-JSON fallback — all running in production, none exercised. Twenty-nine tests were written. One boundary required a non-obvious fix: atomic write failure is validated by patching zenzic.core.cache.json.dump, not builtins.open, because save() uses Path.open(). The distinction is silent and the kind of thing that lets a bad mutant survive indefinitely.

Mutation testing. mutmut was run across rules.py, shield.py, and reporter.py. The survivors diagnosed precisely what was missing. _to_canonical_url had no test targeting its rstrip("/") normalisation, its backslash conversion, or the boolean logic guarding context-aware ..-resolution — a and … or mutation that would make the guard fire on partial input. _obfuscate_secret had no boundary test at len(raw) == 8 (the <= 8 threshold). New mutant-killing test classes were added to make those mutations observable and fatal.

Cross-platform regression. resolve_asset() in all three adapter modules used Path.exists() for fallback path validation. On Windows (NTFS) and macOS (HFS+) this returns True regardless of capitalisation — Logo.png passes when the file on disk is logo.png. A new case_sensitive_exists() helper using os.listdir() enforces exact case on every platform, fixing a CI regression on the Windows and macOS legs of the cross-platform matrix.

CVE-2026-3219. pip 26.0.1 is affected by a polyglot archive vulnerability (no patched release on PyPI). Zenzic uses uv for all package management and never invokes pip programmatically — the exposure is zero. The nox security session was updated to suppress the advisory with a documented removal reminder.

The test count at the close of the parity sprint: 1,195 tests, all passing.

The Precision Sprint: Eliminating False Positives​

After CLI symmetry was established, two false-positive bugs were closed.

BUG-012 — Z502 MDX Frontmatter Leak. The placeholder detector (Z502 PLACEHOLDER) was firing on React-style template expressions inside MDX files — {children}, {props.title} — because the frontmatter extraction boundary was too permissive. The fix constrained YAML extraction to terminate at the first --- close marker, preventing MDX body content from bleeding into the frontmatter scan. No legitimate placeholder finding was affected.

BUG-013 — Z105 pathname:/// False Positive. Docusaurus uses pathname:/// as a pseudo-protocol for links that resolve at build time into absolute paths. Zenzic's absolute link detector (Z105 ABSOLUTE_LINK) was flagging these as portability violations. The fix adds pathname: to the recognised protocol allowlist (Rule R16: Protocol Awareness). Teams migrating Docusaurus projects to Zenzic no longer see spurious Z105 warnings on build-generated links.

The pattern is significant: precision failures are more dangerous than false negatives. A scanner that cries wolf trains engineers to suppress its output — and the one real finding gets lost in the noise. Every false positive is a credibility tax on the tool that emits it.

Total CLI Symmetry: The Sovereign Root Protocol​

The original v0.7.0 release shipped with check all accepting a PATH argument. The other six check sub-commands (links, orphans, snippets, placeholders, assets, references) and init did not. The gap was architectural inconsistency — a tool that claims uniform behaviour with a non-uniform interface.

D060 closed the gap. Every filesystem-interacting CLI command now accepts an optional PATH with full sovereign root semantics:

zenzic check links   ../other-project       # config follows target, not CWD
zenzic check orphans content/               # sub-directory scope
zenzic check assets  /abs/path/to/docs      # absolute paths accepted
zenzic init          /workspace/new-docs    # Genesis Nomad: create and scaffold

The sovereign root protocol ensures configuration follows the target, not the caller. Running zenzic check links ../other-project from your current working directory loads ../other-project/zenzic.toml, not your project's config. Context cannot be hijacked.

D062 added visual confirmation — the resolved scanning target is printed immediately after the Sentinel header when PATH is provided:

  Scanning: ../other-project/docs

For init in Genesis Nomad mode:

  Target: ../new-project

Operators now see exactly which root Zenzic has elected before the first result appears.

The Law of Contemporary Testimony​

In parallel with the code changes, a policy was codified: the Law of Contemporary Testimony.

Code and documentation are a single, indivisible unit of work. No sprint is closed if the documentation still reflects the previous state of the code.

The enforcement mechanism is the Zenzic Structural Map, a mandatory protocol that ensures no sprint is closed unless the documentation is as mature as the code. If a wrapper behavior changed, the architecture diagram must be updated. If a CLI flag was added, the reference must be updated. If an exit code semantic changed, the policy table and the user documentation must both be updated.

This sounds like documentation discipline. It is actually a defect prevention system. The navbar badge drift, the i18n silent fallback, the README links pointing at URL paths that no longer exist — every one of these was a failure of the implicit contract between code author and documentation author. When those roles are collapsed (as they are in any sufficiently small team), the failure mode is: I know this in my head, I'll update the docs later. Later compounds. The Law makes "later" unconstitutional.

The test count at close of all v0.7.0 consolidation sprints: 1,301 passing tests.

The Purity Protocol: Zero Engine Leaks in Core​

One invariant that emerged from the consolidation: validator.py — the heart of Zenzic — must contain no reference to any engine by name. No "docusaurus", no "sidebar", no "navbar". The Core receives a frozenset[str] of navigable paths from adapter.get_nav_paths(). What lives inside that method is the adapter's problem, not the Core's.

This is not aesthetic. It is architectural insurance. A Core that knows about Docusaurus is a Core that will accumulate Docusaurus special-cases. A Core that knows about MkDocs nav-plugins will accumulate MkDocs exceptions. Every engine leak is a future maintenance trap.

The Purity Protocol (confirmed by grep -n "docusaurus\|sidebar\|navbar\|footer" validator.py → 0 matches) is the enforcement gate. Adding a new adapter that modifies validator.py is a protocol violation. The adapter contract is the boundary — everything engine-specific must live behind it.

Part 5 of this series explains what the Purity Protocol unlocks for the Docusaurus adapter specifically — how get_nav_paths() became a Multi-Source Harvester covering sidebar, navbar, and footer simultaneously.

The Safe Harbor Is Open​

v0.7.0 is a point of arrival. The documentation pipeline is verified, the Shield is hardened, the adapters are parity-complete, and the Core is pure. Every claim Zenzic makes about itself — engine-agnostic architecture, sovereign root semantics, zero subprocesses — holds when checked against the actual codebase.

The pipe is probably still leaking somewhere in your documentation — a broken link, a credential fragment in a frontmatter field, a file invisible to every reader because no clickable navigation surface references it. Find out before your users do.

Part 5 → covers what v0.7.0 unlocks for UX-Discoverability and the full product vision.

uvx zenzic lab

Part 4 of the Zenzic Chronicles. For the complete architectural journey, visit the Safe Harbor Blog.

Zenzic finds them before your readers do — before you build, before you deploy, before it's too late.

Step 1 — Launch​

No install. No virtual environment. One command:

uvx zenzic check all ./docs

No browser, no build engine, no heavy framework — a single Python tool cached on first run and ready in seconds from then on.

Step 2 — Read the Report​

You'll see one of two results:

All clear:

✨ Sentinel Seal: All checks passed. Your documentation is clean.

Issues found:

Each finding carries a Zxxx code, a file path, a line number, and a clear description. Fix what's flagged, re-run, and ship with confidence.

Step 3 — Protect Your CI​

One line in your GitHub Actions workflow:

- name: Audit documentation

  run: uvx zenzic check all ./docs

Every pull request is now guarded. Broken links, orphan pages, and leaked credentials are caught before they reach main.

Why Zenzic​

• Fast — Zenzic is fast because it's lightweight. No build step, no Node.js,

  no browser launch. Analysis happens directly on your Markdown source files.

• Safe — Zenzic is secure because it doesn't touch your system files.

  Read-only analysis, always. Your repository is observed, never modified.

• Universal — Works with MkDocs, Docusaurus, Zensical, or any plain Markdown folder.

  Point it at your docs/ directory and it figures out the rest.

Go Further​

Pin a specific version for reproducible CI:

uvx "zenzic==0.7.0" check all ./docs

The full engineering story behind Zenzic — from the first broken pipe to Quartz Maturity — lives in The Zenzic Chronicles →

For a 1,525-line architectural deep-dive into every Zenzic component — verified by 1,301 tests across Python 3.11, 3.12, and 3.13 — see the Obsidian Masterclass →.

Four bypass vectors. Four real findings. All closed.

This is the complete technical post-mortem of Operation Obsidian Stress — the adversarial security audit we ran against Zenzic v0.6.1rc2's Shield (credential scanner) before release. I'm publishing the full technical details because the findings are instructive, the fixes are non-obvious, and the code belongs in the open.

What Shield Is (and Why Breaking It Matters)​

Before the attack details, context: Shield is Zenzic's credential detection layer. It scans every Markdown and MDX file in your documentation before the build runs, looking for patterns that indicate real credentials in content.

The threat model is simple: a contributor submits a PR with a code example. That example contains a real API key — copied from a local terminal session, pasted from a Slack thread, or forgotten after a debugging session. The reviewer reads the prose, not the bytes. The PR merges. The docs build. The key is now live on your documentation site, indexed by search engines.

Shield exists to catch that before it ships. If Shield can be bypassed by someone who knows how it works, it's not a scanner — it's a false guarantee.

The Attack Surface​

Shield's architecture before Operation Obsidian Stress:

1. Read each line of the Markdown/MDX file
2. Apply a normalization pass (strip backticks, collapse whitespace)
3. Run 9 regex patterns against the normalized line
4. Report any match as a ShieldFinding

Step 4 triggers Exit Code 2 (Shield breach) — non-bypassable, distinct from Exit Code 1 (validation failure) and Exit Code 3 (Blood Sentinel / path traversal).

The attack surface was step 2: the normalization pass. It normalized formatting noise but did not account for deliberate obfuscation.

ZRT-006: Unicode Format Character Injection​

Category: Input normalization bypass Severity: High — complete bypass of all regex patterns CVSS analogy: 8.1 (High)

The Technique​

Python's unicodedata module exposes a character category classification. The Cf category ("Format characters") includes characters that are semantically meaningful in Unicode text processing but are invisible in rendered output and most text displays:

Inject any of these into a credential token and the regex fails to match:

key = "sk-abc123def456ghi789jkl012mno345pqr678stu"
# Insert ZWS after position 9 (inside the token)
bypass = key[:9] + "\u200B" + key[9:]

import re
pattern = re.compile(r"sk-[a-zA-Z0-9]{48}")
print(pattern.search(bypass))  # None — bypass confirmed

The Fix​

Strip all Cf-category characters before any normalization step runs:

import unicodedata

def _strip_unicode_format_chars(text: str) -> str:
    """Remove all Unicode Format (Cf) characters.

    Invisible to human readers but interrupt regex pattern matching.
    Examples: U+200B (ZWS), U+200C (ZWNJ), U+200D (ZWJ), U+00AD (soft hyphen).
    """
    return "".join(c for c in text if unicodedata.category(c) != "Cf")

ZRT-006b: HTML Entity Obfuscation​

Category: Input normalization bypass Severity: High — bypasses patterns that depend on punctuation characters Affected families: OpenAI (hyphen), Stripe (hyphen, underscore), GitHub (underscore)

The Technique​

Markdown renderers decode standard HTML entities. The hyphen character (-) has the HTML entity -. The underscore (_) is _.

sk-abc123def456ghi789jkl012mno345pqr678stu

Renders as: sk-abc123def456ghi789jkl012mno345pqr678stu — a valid OpenAI key format.

The credential scanner sees sk-abc123... — which does not match sk-[a-zA-Z0-9]{48}. The entity is a one-character substitution of a structural boundary character.

The Fix​

import html

def _decode_html_entities(text: str) -> str:
    """Decode HTML entities before pattern matching.

    A credential containing - (hyphen) or _ (underscore) renders
    correctly in a browser but bypasses regex patterns that match on the
    literal character.
    """
    return html.unescape(text)

html.unescape() is part of the Python standard library. No dependencies. Zero cost.

ZRT-007: Comment Interleaving​

Category: Token fragmentation via markup Severity: High — renders the token non-contiguous in raw source Technique: Inject HTML or MDX comment blocks between credential characters

The Technique​

HTML comments and MDX expression comments are invisible in rendered output. They are valid Markdown syntax that any Markdown renderer will process and discard.

sk-abc123<!-- This is a comment, nothing to see here -->def456ghi789jkl012mno345pqr678stu

In rendered output: sk-abc123def456ghi789jkl012mno345pqr678stu (correct, readable). In raw source the scanner reads: the regex fails because the comment block interrupts the character class [a-zA-Z0-9].

MDX variant: sk-abc123{/* inline MDX comment */}def456... — same effect.

The Fix​

import re

_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
_MDX_COMMENT_RE = re.compile(r"\{/\*.*?\*/\}", re.DOTALL)

def _strip_markup_comments(text: str) -> str:
    """Strip HTML and MDX comments before pattern matching."""
    text = _HTML_COMMENT_RE.sub("", text)
    text = _MDX_COMMENT_RE.sub("", text)
    return text

ZRT-007b: Cross-Line Token Splitting​

Category: Architectural bypass — stateless scanner assumption Severity: Critical — bypasses all pattern matching with zero obfuscation Technique: Line break

This is the most architecturally significant finding. It requires no Unicode tricks, no entity encoding, no markup injection. One line break.

The Technique​

Here is my staging key for the integration tests: sk-abc123def456
ghi789jkl012mno345pqr678stu901vwx234yz

The scanner processes line 1 — no match (only 12 chars after sk-). The scanner processes line 2 — no match (no sk- prefix). The credential leaks. The split is invisible in rendered output — the two lines render as a single paragraph.

The Fix: The Lookback Buffer​

A stateful generator that maintains context across line boundaries, creating a synthetic overlap zone:

def scan_lines_with_lookback(
    lines: Iterable[tuple[int, str]],
    file_path: Path,
    buffer_width: int = 80,
) -> Iterator[ShieldFinding]:
    prev_normalized: str = ""
    prev_seen: set[str] = set()

    for line_no, raw_line in lines:
        seen_this_line: set[str] = set()
        normalized = _normalize_line_for_shield(raw_line)

        # Pass 1: standard per-line scan
        for finding in _scan_normalized_line(normalized, file_path, line_no):
            yield finding
            seen_this_line.add(finding.family)

        # Pass 2: cross-line join zone scan
        if prev_normalized:
            join_zone = prev_normalized[-buffer_width:] + normalized[:buffer_width]
            for finding in _scan_normalized_line(join_zone, file_path, line_no):
                if finding.family not in (seen_this_line | prev_seen):
                    yield finding

        prev_normalized = normalized
        prev_seen = seen_this_line

Why 80 characters? Standard terminal width and most documentation editors wrap at 80–120 characters. Taking 80 characters from each side covers the vast majority of real-world split positions with minimal false positive risk.

The Complete 8-Step Normalization Pipeline​

After closing all four vectors, Shield's normalization function runs every line through a deterministic eight-step sequence:

def _normalize_line_for_shield(raw_line: str) -> str:
    text = raw_line
    text = _strip_unicode_format_chars(text)   # Step 1: Cf chars
    text = html.unescape(text)                  # Step 2: HTML entities
    text = _HTML_COMMENT_RE.sub("", text)       # Step 3: HTML comments
    text = _MDX_COMMENT_RE.sub("", text)        # Step 4: MDX comments
    text = _BACKTICK_RE.sub(lambda m: m.group(1), text)  # Step 5: backtick spans
    text = text.replace("+", " ")              # Step 6: concatenation operators
    text = text.replace("|", " ")              # Step 7: table cell separators
    text = " ".join(text.split())              # Step 8: whitespace collapse
    return text

Each step is independently testable. The test suite includes 47 tests specifically for normalization.

Coverage Added by Operation Obsidian Stress​

Before the operation: 929 passing tests. After closing all four vectors: 1,130+ passing tests.

The Risk Management Dimension​

The four bypass vectors found during Operation Obsidian Stress have a common property: they are not obscure edge cases. They are techniques that appear in standard lists of regex evasion methods used in adversarial content scenarios — discoverable by any documentation contributor with moderate knowledge of Unicode, HTML encoding, and regex mechanics.

The risk profile of an unpatched documentation scanner is not “low probability, low impact.” It is moderate probability, high impact — because credential leaks in documentation have immediate material consequences, and because documentation pipelines receive content from the broadest possible contributor population.

This is the supply chain risk dimension that is most frequently underweighted: not the vulnerability of your infrastructure, but the vulnerability of the content processing path you expose to your contributor base.

A security tool that can be bypassed by a contributor who knows how it works is not a security tool. It is a compliance checkbox.

Beyond Security: The Full Zenzic Surface​

Shield is one layer in a complete documentation quality framework:

All analysis is engine-agnostic: auto-detection covers MkDocs, Docusaurus v3, Zensical, and Standalone Mode. No plugins to install. No build to run. No subprocesses.

Exit Code Taxonomy​

Zenzic’s exit codes are non-negotiable — no configuration can suppress them:

Codes 2 and 3 cannot be configured away. A CI step that can be silenced on a security failure is not a security control.

The Obligation of the Bastion​

“The Bastion holds” is not a marketing phrase. It is an engineering commitment. It means that every identified attack path has been closed, that the closure has been verified with test coverage, and that the system’s failure modes under adversarial input are bounded and known.

It does not mean that future bypass vectors don’t exist. Red team exercises are not proofs of security — they are evidence of the security posture at a specific moment in time. The four vectors found during Operation Obsidian Stress were found because we looked for them systematically. Vectors we haven’t enumerated may still exist.

What the Bastion commitment means is that we look — methodically, adversarially, and transparently about what we find.

The Takeaway​

The four bypass vectors found during Operation Obsidian Stress are not exotic. They're the kind of techniques that appear in any list of regex evasion methods — Unicode injection, HTML entity encoding, markup comment interleaving, structural line splitting.

What made them findable was the decision to look for them systematically, with adversarial intent, before release. What made them fixable was having a normalization pipeline with defined semantics and comprehensive test coverage at each step.

Security tooling that isn't tested adversarially is security tooling that provides the appearance of coverage without the substance.

Cross-posted on:

• Medium — We Put Our Documentation Linter Under an AI-Driven Siege

Part 3 of the Zenzic Chronicles. For the complete architectural journey, visit the Safe Harbor Blog.

v0.6.1rc2 — Obsidian Bastion is the release that turned Zenzic from a capable single-engine linter into a genuine multi-engine documentation Safe Harbor.

The architectural shift​

The defining change of the Bastion cycle was the rejection of a hidden assumption: that every project using Zenzic would have a single, knowable documentation engine.

That assumption broke the moment we tried Zensical — a MkDocs-compatible engine with its own configuration surface. The fix was not to add another adapter. It was to rethink the adapter contract entirely.

Headless Architecture (Pillar 1, enforced)​

Every adapter was refactored to receive a pre-built context object — BuildContext — rather than reading configuration files at runtime. This eliminated the last class of I/O in the hot path and made the system deterministically testable.

New in v0.6.1rc2​

Shield hardening: four bypass vectors closed​

The security audit that ran concurrently with the Bastion architecture work found and closed four bypass vectors in the Shield credential scanner — the module responsible for detecting leaked credentials before any documentation build begins.

Two additional hardening measures were applied in this cycle:

Blood Sentinel (Exit 3). A dedicated fatal exit code was formalised for architectural violations — docs_dir paths that escape the repository root now trigger Exit 3 before any scan begins. This is not a lint finding. It is a hard stop.

ReDoS protection. Lines exceeding 1 MiB are silently truncated before regex matching, preventing catastrophic backtracking against adversarially crafted inputs.

Operation Obsidian Stress​

During the v0.6.1rc2 cycle, an AI-driven adversarial audit found four bypass vectors in the Shield credential scanner. All four were closed before the release candidate was finalised. The complete post-mortem is published here:

→ We Put Our Documentation Linter Under an AI-Driven Siege

The full architectural story of the Bastion cycle:

→ What Happens When You Rip the Foundation Out of a Security Tool

Most documentation builds operate on an implicit contract with their input: the content is trusted because the contributors are trusted. It's a reasonable assumption for a wiki. It is an indefensible posture for a security-conscious CI pipeline.

Zenzic was built to invalidate that assumption — to treat documentation the way a compiler treats source: as input that must be analyzed, validated, and potentially rejected before it reaches production.

If your documentation is part of your CI pipeline, it's part of your attack surface. Zenzic is designed for CI pipelines that handle untrusted docs, open-source projects with external contributors, and teams running multiple doc engines side by side.

In Part 1, I covered the philosophy and threat model. This piece is about how Obsidian Bastion enforced them as infrastructure properties.

🎯 Where Zenzic Fits​

Zenzic is designed for:

• CI pipelines that handle untrusted docs
• Open-source projects with external contributors
• Teams running multiple doc engines side by side
• Security-conscious workflows that need to validate content before the build — not after

Three core properties define it:

No subprocess execution — ever. No node, no git, no shell calls. The core library is 100% Pure Python. This isn't a convenience feature — it's a security model. A tool that spawns subprocesses is a tool that can be tricked into executing untrusted code.

Engine-agnostic analysis. Zenzic reads raw Markdown and configuration files as plain data. It never imports or executes a documentation framework. Engine-specific knowledge lives in thin, replaceable adapters that translate semantics into a neutral protocol.

Deterministic file discovery. Every file scan is explicit. Every path is validated. There are no accidental full-repo traversals, no hidden directories slipping through. Identical source files always produce identical results.

The Versioning As a Threat Model​

Understanding what changed in the Obsidian series requires understanding what the previous version got wrong.

The Sentinel was a capable linter. It was also architecturally coupled to a single documentation engine. When a MkDocs assumption was embedded in the core, the core had opinions about what “valid documentation” meant that had nothing to do with the content being analyzed.

This coupling is a risk. An analyzer that assumes its input follows MkDocs conventions will fail silently — or not at all — when presented with a Docusaurus project. Failing silently is the worst possible outcome for a security tool: it gives a false sense of coverage.

The biggest single commit in this arc deleted 21,870 lines and added 888 — the Headless Architecture transition that stopped Zenzic from being a MkDocs tool and made it an analyser of documentation platforms.

⚛️ Parsing Docusaurus without Node​

The first concrete challenge was supporting Docusaurus v3. Its config files are TypeScript:

export default {
  presets: [['classic', { docs: { routeBasePath: '/guides' } }]],
  i18n: { defaultLocale: 'en', locales: ['en', 'it'] },
};

The obvious solution — calling node to evaluate the config — would violate Pillar 2 (No Subprocesses). So I built a static parser in Pure Python that extracts baseUrl, routeBasePath, locale configuration, and plugin metadata directly from the source text. No evaluation. No runtime. No JavaScript.

🧱 Layered Exclusion — The Real Headline Feature​

File discovery is where most documentation tools quietly fail. The Layered Exclusion Manager replaces all ad-hoc directory filtering with a deterministic 4-level hierarchy:

The levels encode a security invariant: L1 System Guardrails are immutable. No configuration file and no CLI flag can force Zenzic to scan inside .git/ or node_modules/.

🗡️ The Tabula Rasa Refactor​

The most invasive change: I removed every single rglob() call from the codebase — all of them — and replaced them with two centralized functions in discovery.py:

def walk_files(root, exclusion_manager) -> Iterator[Path]: ...
def iter_markdown_sources(root, exclusion_manager) -> Iterator[Path]: ...

The exclusion_manager parameter is mandatory. Not Optional, no None default. If you call a scanner or validator entry point without an ExclusionManager, you get a TypeError at call time — not a silent full-tree scan at runtime.

168 call sites updated. Accidental full-repo scans are now architecturally impossible.

🔐 Security Hardening​

ReDoS prevention. Lines exceeding 1 MiB are silently truncated before Shield regex matching. A crafted documentation file with a multi-megabyte line could exploit catastrophic backtracking in credential detection patterns.

Path traversal guard (Exit Code 3). _validate_docs_root() now rejects docs_dir paths that escape the repository root. A malicious zenzic.toml pointing docs_dir: ../../../etc/ triggers Exit 3 (Blood Sentinel) before any file is read.

The Supply Chain Risk Metric That Doesn't Get Enough Attention​

Runtime dependency count is an underappreciated supply chain security metric.

Every Python package that Zenzic imports at runtime is a potential vector for dependency confusion attacks, malicious package updates, and transitive vulnerability inheritance. The decision to minimize the dependency surface is not about keeping the package small — it is about limiting the attack surface of the supply chain.

Zenzic's runtime dependency count: 5.

For a tool that supports four documentation engines, performs multi-family credential detection, implements a deterministic quality scoring system, validates link graphs against a virtual site map, and runs over a thousand tests — five runtime dependencies is a deliberate architectural achievement, not a limitation.

What "Hardened" Actually Means​

The word “hardened” is overused in security marketing. In the context of Obsidian Baston, it has a specific meaning: every component of the system has been analyzed for its failure modes under adversarial input, and those failure modes have been either eliminated or bounded.

The subprocess constraint eliminates the execution trust boundary. The Layered Exclusion Manager bounds the filesystem access surface. The mandatory ExclusionManager type enforces the boundary at the API level. The non-bypassable exit codes ensure that security failures produce unambiguous CI outcomes. The ReDoS truncation bounds the computational cost of analysis. The path traversal guard bounds the filesystem read scope.

None of these are features. They are the removal of assumptions — the careful, systematic elimination of the implicit trust that characterizes unexamined systems.

A hardened system is not a system with more defenses added on top. It is a system with fewer assumptions built in.

What Broke Along the Way​

A refactor of this scope does not leave the API surface intact. Three breaking changes were deliberate, not accidental:

• zenzic serve removed entirely — use your engine's native command (mkdocs serve,

  npx docusaurus start). It was the last place where a subprocess could theoretically be spawned.

• MkDocs plugin relocated from zenzic.plugin to zenzic.integrations.mkdocs,

  installs separately via pip install "zenzic[mkdocs]", keeping the core free of engine-specific imports.

• ExclusionManager parameter is now mandatory — no Optional, no None default.

  If your code was silently skipping exclusion filtering, it will now fail at the type level. That's the point.

These are costs. They are also the reason the guarantees in this article are enforceable rather than aspirational.

📊 By the Numbers​

🏁 Run It Against Your Docs​

pip install zenzic
zenzic check all

Cross-posted on:

• Medium — What Happens When You Rip the Foundation Out of a Security Tool

Part 2 of the Zenzic Chronicles. For the complete architectural journey, visit the Safe Harbor Blog.

v0.6.0a1 — The Sentinel is the founding alpha: the release that crystallised the philosophy of Zenzic from a prototype into a disciplined engineering system.

What shipped​

This alpha established three architectural pillars that remain non-negotiable to this day:

1. Lint the Source — Zenzic never runs the build. It reads raw Markdown and configuration

   files directly. HTML output is never trusted.

2. No Subprocesses — 100% pure Python. No subprocess.run, no Node.js execution,

   no external process calls in the hot path.

3. Pure Functions First — Deterministic logic. No I/O inside link-validation loops.

Core capabilities in v0.6.0a1​