The ReDoS Problem in CI/CD​

Many Python-based linters rely on the standard re module, which uses a backtracking NFA-style regex engine. When evaluating complex regex patterns against large or crafted payloads, backtracking can lead to exponential worst-case time complexity: $O(2^N)$.

In a CI/CD environment, an attacker or a simple misconfiguration can introduce a payload that triggers this exponential evaluation. This can stall a pipeline for impractically long periods of time, consuming runner minutes and effectively causing a denial of service on the build infrastructure. Traditional tools attempt to mitigate this using timeouts (SIGALRM or runtime canaries), but these are operational bandages, not architectural solutions.

The Zenzic Solution: DFA and Algorithmic Separation​

Zenzic solves this by completely decoupling the algorithmic approaches based on the problem domain, applying domain-appropriate algorithmic bounds to each layer.

By banning Python's re module and adopting google-re2, Zenzic avoids catastrophic backtracking. RE2 processes input without exponential fallback strategies, ensuring a linear time complexity of $O(N)$, where $N$ is the length of the text.

Architectural Summary​

The architectural decisions are summarized below:

Structural Validation vs. Semantic Scanning​

1. Topology (Knowledge Graph): Zenzic treats documentation as a directed adjacency graph. Link validation uses an iterative Depth-First Search (DFS). Using an adjacency list representation, the traversal complexity is $\Theta(V+E)$. The resulting cycle registries are stored as hash sets, allowing average $O(1)$ lookups during the secondary validation pass.

2. Semantic Scanning: Credential scanning and custom rules use the aforementioned approach via google-re2. This ensures linear $O(N)$ semantic scanning, eliminating ReDoS vulnerabilities based on exponential backtracking.

3. I/O Discovery: The ingestion phase operates in $O(N)$ complexity relative to the total volume of processed data. To reduce wall-time without altering the fundamental computational complexity, Zenzic can distribute processing via parallel process pools.

This algorithmic separation ensures that Zenzic remains a structurally sound, security-hardened tool capable of operating safely within enterprise CI/CD gates.

v0.9.0 establishes deterministic telemetry as a release-level engineering contract across core, action, and docs.

1) Flat-Cost DQS Shift​

The quality score now treats every active suppression as a uniform debt signal:

• one suppression equals one score-point deduction;
• suppression debt is always visible in the final score;
• governance thresholds are evaluated independently from debt accumulation.

This closes long-standing ambiguity between enforcement outcomes and score telemetry.

2) BaseAdapter Legacy Method Removal​

v0.9.0 finalizes adapter contract simplification by removing legacy dual-method surfaces in favor of a single route-information path.

Migration focus:

• remove legacy adapter method surfaces from custom implementations;
• keep routing semantics deterministic at a single integration boundary;
• reduce divergence between link resolution and classification behavior.

3) Native Freshness Gate via --check-stamp​

Telemetry is now enforced through a native freshness command:

• zenzic score --check-stamp verifies badge freshness deterministically;
• freshness checks are config-aware through declared stamp targets;
• CI and local pre-push gates share the same telemetry contract.

Outcome​

v0.9.0 turns telemetry from a side-channel metric into a deterministic release surface: inspectable, reproducible, and enforceable in every gate stage.

Zenzic is designed to run inside automated pipelines without configuration drift. On the v0.9.0 line, three patterns appear consistently in production deployments: a quality gate that blocks merges on score regression, a containment strategy for repositories with accumulated link debt, and an i18n parity gate enforcing structural symmetry across translations.

These patterns target different teams at different stages: DevOps teams enforcing merge gates in CI, technical leads scoping governance adoption in repositories with accumulated debt, and documentation engineers maintaining multilingual portals. The patterns are independent and can be combined. A repository with legacy debt can run Pattern 2 to fence exemptions while still enforcing a quality floor via Pattern 1 and structural i18n parity via Pattern 3.

Pattern 1 — CI/CD Quality Gate​

Documentation quality drift rarely looks catastrophic in isolation. A broken link here, a suppressed warning there — each individually justifiable. The aggregate effect is a score that drifts down one point per release cycle until the baseline expectation shifts downward to match. The suppression count is the critical signal: when teams learn that adding a zenzic:ignore directive prevents a CI failure, the suppression budget becomes the real quality floor rather than the score threshold. Both conditions need to be gated independently.

A quality gate blocks a merge if the documentation score falls below a threshold or if the active suppression count exceeds a budget. Both conditions can co-exist independently.

Configuration:

[governance]
fail_under = 80
suppression_cap = 15

fail_under is a mathematical floor: Zenzic computes the weighted score and exits with code 1 if it falls below 80. suppression_cap is a count ceiling: if more than 15 zenzic:ignore directives are active at the time of the check, exit code 1 is issued regardless of the computed score.

GitHub Actions integration:

- name: Check documentation quality
  run: zenzic check all --strict

--strict elevates all warning-severity findings to error. Combined with fail_under, this enforces both a minimum score and a zero-warning policy. The two controls are independent: removing --strict does not change the score; lowering fail_under does not relax the warning policy.

zenzic diff for regression detection:

zenzic diff main

Compares the quality score of the current branch against main. Exits with code 1 on regression. Suitable for pull request checks where the absolute score is acceptable but a branch-local regression is not.

Pattern 2 — Legacy Debt Containment​

The most common reason teams delay governance adoption is accumulated technical debt. A repository with hundreds of broken links in archived migration guides, deprecated API references, or legacy tutorials cannot pass a strict quality gate without a remediation campaign first — which blocks every other improvement. The result is that governance tooling goes unconfigured rather than progressively adopted. governance.directory_policies breaks this deadlock by fencing the debt structurally without touching the affected files.

Repositories with historical documentation debt — archived migration guides, deprecated API references, legacy tutorials — accumulate broken links and stale brand references over time. Eradicating debt from exempted directories blocks releases unnecessarily. governance.directory_policies fences it instead.

Configuration:

[governance.directory_policies]
"docs/archive/**" = ["Z101", "Z102", "Z601"]
"docs/legacy/**"  = ["Z101", "Z601"]

Each key is a glob pattern relative to docs_dir. The value is a list of finding codes suppressed for every file that matches. Suppressed findings do not contribute to the quality score for those files and do not count against suppression_cap.

This approach isolates the debt rather than distributing inline zenzic:ignore directives across hundreds of legacy files. The governance policy remains visible, auditable, and centralized in .zenzic.toml.

Auditing the exempted directories:

zenzic check all --audit

--audit bypasses all suppressions — including governance.directory_policies — and reports every finding with a [POLICY_EXEMPTION] label. Use this during periodic debt review cycles to quantify the residual finding count before deciding whether to reduce the exemption scope.

Pattern 3 — Sovereign I18N Parity​

Locale drift is invisible at authoring time. A contributor adding a new reference page to the English site has no immediate feedback that the Italian mirror is now structurally incomplete. The gap only surfaces when a translated-site user encounters a 404, or when a periodic manual audit catches it — neither of which scales as the documentation site grows. Z602 surfaces this gap at every CI run, before the missing translation reaches production.

Multilingual documentation sites accumulate structural drift: pages added to the default locale are not mirrored in secondary locales, leaving translated sites incomplete. Z602 I18N_PARITY detects this gap at the structural level.

Configuration:

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

When strict_parity = true, every page present in default_locale must have a counterpart in every other locale. Missing translations surface as Z602 I18N_PARITY findings at error severity.

Enforcement in CI:

zenzic check all --strict

Z602 findings are error-severity by default. --strict is not required to block the pipeline on I18N_PARITY violations; it ensures that no other warning-class finding silently passes alongside them.

Gradual adoption:

If the translation backlog is substantial, set strict_parity = false initially and use governance.directory_policies to suppress Z602 for specific locale directories that are still under active translation work:

[governance.directory_policies]
"i18n/it/docusaurus-plugin-content-docs/current/reference/**" = ["Z602"]

Remove the exemption when the translation reaches structural parity. zenzic diff main confirms the removal does not regress the quality score.

A linter reports violations within individual files. A governance engine verifies that a set of invariants holds across the entire document graph — and halts the pipeline when one does not.

This analysis reflects the terminal contract as shipped on the v0.9.0 release line.

Beyond Linting​

The distinction between a linter and a governance engine is not one of depth. It is one of scope and contract type.

A linter's analysis terminates at the file boundary. It reports violations of formatting rules — incorrect indentation, undefined references within a single file, missing required metadata fields. Each file is processed independently, in isolation. The diagnostic is local: a violation in file-a.md has no bearing on the analysis of file-b.md.

Zenzic operates on a different unit: the document graph. A single invocation of zenzic check all evaluates the entire scope defined by the adapter configuration — every internal link, every navigation contract, every credential surface, every suppression directive — as a unified object. No file is analyzed in isolation, because no documentation system exists in isolation. A broken internal link is not a property of the page that contains it. It is a property of the relationship between two nodes in the graph. An orphaned page is not detectable from within that page. It is detectable only when the navigation manifest is resolved against the full file tree.

This distinction has a direct consequence for the design of the terminal output. When the unit of analysis is a graph, a single-line error message is insufficient. The interface must communicate: what the violation is, where in the file it occurs, which contract it violates, and enough surrounding context for the reader to understand the issue without opening the source file.

Zenzic exposes two orthogonal instruments for evaluating the document graph:

• zenzic check — a binary gate. It returns an exit code in {0, 1, 2, 3} and a structured list of findings. The exit code is the contract with CI: deterministic, machine-readable, with semantics that hold regardless of configuration.
• zenzic score — a weighted penalty model. It returns a Documentation Quality Score (DQS) in the range 0–100, decomposed by diagnostic category. The output is audit-oriented: it answers not whether the documentation passes, but by how much and in which domains it deviates from the governance baseline.

Both instruments share the same analysis engine. They answer different questions.

The rest of this article examines each layer of the terminal interface that implements these contracts: the run header, the diagnostic renderer, the suppression audit model, and the exit code semantics.

Information Density in the Run Header​

At the end of every zenzic check invocation, a single telemetry line is printed below the findings list:

standalone • 20 files (14 docs, 6 assets) • 0.8s • 38 files/s

This line encodes four independent signals. Each field answers a distinct operational question.

Adapter mode (standalone). Zenzic resolves the adapter from the project configuration at startup. Supported modes include docusaurus, mkdocs, zensical, and standalone. The adapter determines the navigation contract: which files constitute the document graph, how routes are resolved, and which structural checks are active. When no recognized configuration file is present, standalone is the default.

The adapter label carries a constraint that is not stated elsewhere in the output. In standalone mode, the navigation manifest is absent. Checks that require a resolved route graph — orphaned-page detection being the primary example — are structurally inactive for that run. The label is the sole communication of this fact.

Scope decomposition (20 files (14 docs, 6 assets)). The file count is split into two categories: documents (.md and .mdx) and assets (images, data files, schema definitions, and any other non-document file within the analyzed tree). The split is not cosmetic: document checks operate on file content; asset checks operate on the asset manifest. Different scanners activate for each category.

The analyzed scope is bounded by docs_dir and excluded_dirs in .zenzic.toml. Files outside this boundary are not evaluated, regardless of their position in the repository tree. The counts in the footer reflect exactly the scope that was evaluated — nothing more, nothing less.

Elapsed time (0.8s). Wall-clock duration from invocation to the final diagnostic line. This includes file I/O, adapter resolution, and all analysis passes. It is not a CPU-time measurement. On the same hardware and the same scope, consecutive runs produce consistent values, making elapsed time a reproducibility indicator without additional instrumentation.

Throughput (38 files/s). Derived as scope divided by elapsed time. The value is hardware-specific and not portable across machines. Its utility is local: establishing a baseline on a given host makes performance regressions in the analysis pipeline detectable before they affect CI wall time.

To enumerate the full scanner manifest active for a given configuration — codes, capabilities, and exit-code contracts — use zenzic inspect.

Diagnostic Rendering​

A finding is self-describing. It carries enough information for triage without opening the source file, navigating the repository, or invoking additional tools. This property is not incidental — it is a design constraint that shapes every layer of the diagnostic output.

Each finding is rendered as a three-layer block.

Layer 1 — Finding header. The first line identifies the finding unambiguously: file path, line number, column (when available), Z-code, and message. The Z-code is the machine-readable identifier of the violated contract. The message is a human-readable description of the violation.

docs/guides/install.md:47:29
✘ Z101  Broken internal link → install.md

Layer 2 — Source snippet. Five lines of source context are shown: two lines before the error line, the error line itself, and two lines after. Context lines are rendered with a │ gutter marker in muted style. The error line is rendered with a ❱ gutter marker in error style.

     45  │  ## Installation Prerequisites
     46  │
     47  ❱  See the [Installation Guide](install.md) for details.
     48  │
     49  │  Continue to the Configuration section when ready.

This window is the primary triage surface. The two lines of context before the error establish what the offending line belongs to — a section header, a paragraph, a list item. The two lines after establish what follows. In a CI log, this eliminates the need to reproduce the run locally, open the file, or reconstruct the surrounding context manually. The context-switching overhead between reading a pipeline failure and understanding its location is zero.

Layer 3 — Caret row. When the scanner that produced the finding also provides the exact byte offset of the matched token in the source line, a caret row is rendered immediately below the error line. The caret spans the matched token precisely.

     47  ❱  See the [Installation Guide](install.md) for details.
            │                             ^^^^^^^^^^

The caret length equals the length of the matched string. The caret start position equals the byte offset of that string in the raw source line — the exact value returned by the pattern match, with no rounding, padding, or adjustment. If the scanner does not report a native column position, the caret row is omitted entirely. There is no fallback, no estimation, and no approximation. A caret in the output is always exact; the absence of a caret means the scanner operates at line granularity rather than token granularity.

The practical consequence: for findings where column data is available — such as credential detections and inline link violations — the operator sees the precise token that triggered the finding. No surrounding content requires manual inspection.

The three layers together form a self-contained diagnostic unit:

docs/guides/install.md:47:29
✘ Z101  Broken internal link → install.md

     45  │  ## Installation Prerequisites
     46  │
     47  ❱  See the [Installation Guide](install.md) for details.
            │                             ^^^^^^^^^^
     48  │
     49  │  Continue to the Configuration section when ready.

The Mathematics of Suppression Debt​

The zenzic:ignore inline directive tells Zenzic to skip the finding on the annotated line. Each active directive — whether applied inline or via the per-file suppression list in .zenzic.toml — costs exactly one point from the Documentation Quality Score. No directive is free.

This is the flat-cost model. It replaced an allowance-based model in which a configured number of suppressions carried no penalty, and costs applied only to the excess. The allowance model produced a predictable outcome: teams treated the free allowance as a budget to fill, not a limit to avoid. A model in which the first N suppressions are free and the (N+1)th costs a point is not a governance model — it is a permission slip. The incentive it creates is to suppress freely below the free threshold and worry about governance only after that line is crossed.

Under the flat-cost model, the first suppression costs one point. The tenth costs one point. There is no free zone. The suppression_cap value configured in .zenzic.toml is not an allowance — it is a hard-fail ceiling. When the suppression count exceeds the cap, the build fails regardless of the numeric score.

The DQS formula. The Documentation Quality Score is computed in three stages. First, per-category subtotals:

Where:

• $C_i$ is the point cap for category $i$: Structural (30), Navigation (25), Content (20), Brand & Governance (25).
• $D_i = \sum_{c \in i} p_c \cdot k_c$ is the total penalty for category $i$: the sum of per-code penalty $p_c$ multiplied by finding count $k_c$, for all codes assigned to that category.
• $n_{\text{sup}}$ is the total count of active suppression directives, each contributing exactly 1 point of deduction.

Two invariants constrain the formula:

• Category Cap Invariant. Deductions within a category cannot exceed the category cap. One thousand occurrences of a 1-point finding in the Content category deduct at most 20 points — the Content cap. The remaining categories are unaffected.
• Gravity Cap. If the Brand & Governance category is fully zeroed by findings, the category subtotal is capped at 70. Uncontrolled governance violations impose a structural ceiling on the total score regardless of how other categories perform.

Suppression debt ($n_{\text{sup}}$) is applied after both invariants, as a final deduction from the adjusted subtotal.

The Quality Breakdown Ledger. The zenzic score command renders a per-category table that exposes the deduction mechanics:

 Quality Breakdown
 ─────────────────────────────────────────────────────────
   Category      Issues  Weight   Raw Pts      Applied Pts
 ✔ structural         0    30%          0                0
 ✔ navigation         0    25%          0                0
 ✔ content            0    20%          0                0
 ✘ brand             42    25%        -60     -25 (CAPPED)
 ─────────────────────────────────────────────────────────
   Σ Subtotal                                           75

  ! Gravity Cap Enforcement (Brand = 0):   -5 pts
  ! Technical Debt (5 suppressions):       -5 pts
  = Final Quality Score                    65 / 100

Raw Pts is the total deduction accumulated within the category before the cap is applied. Here, 42 brand findings produced −60 raw points. Applied Pts is the deduction after the category cap: the Brand cap is 25 points, so the applied penalty is −25. The (CAPPED) marker confirms that the raw deduction was truncated by the cap boundary. The difference between Raw Pts and Applied Pts is not recovered — it signals that the category has been fully zeroed.

The ! Gravity Cap Enforcement line appears when the zeroed Brand category causes the subtotal to be reduced from 75 to 70, applying a 5-point structural penalty. The ! Technical Debt line shows the flat-cost deduction: five active suppression directives produce a deduction of five points, applied after all category calculations.

The suppression count is also compared to governance.suppression_cap. When the count exceeds the cap, the build fails with a distinct message:

FAILED: suppression cap exceeded (36/30).
Update governance.suppression_cap in .zenzic.toml if intentional.

This failure is Exit 1 and remains fail-hard when suppression cap is exceeded. It cannot be resolved by adding more zenzic:ignore directives — each additional directive increases the count and the debt simultaneously.

Exit Semantics as a CI Contract​

The exit code is not a summary of the terminal output. It is the primary contract between Zenzic and the CI pipeline. The pipeline reads the exit code, not the display. The display is for operators; the exit code is for automation. This distinction determines how the exit semantics are designed.

The four exit codes and their contracts:

Exit 0. The analyzed scope contains no error-severity findings. When fail_under is configured, a score below the threshold also produces Exit 1 — so Exit 0 confirms both the absence of findings and that the Documentation Quality Score meets the configured threshold. The scope qualifier is precise: files outside the configured docs_dir boundary are not evaluated, and their state is not reflected in the exit code.

Exit 1. One or more error-severity findings were detected, or the suppression count exceeded governance.suppression_cap. This is the standard CI gate. --exit-zero converts Exit 1 to Exit 0 only for the standard error-findings path; suppression-cap failures remain fail-hard. The conversion does not suppress findings from the output — they remain visible in the terminal. --exit-zero cannot be combined with --strict; Zenzic rejects that combination with Exit 2 at startup.

Exit 2. A finding with security_breach severity was produced — meaning a credential or secret was detected in the documentation source tree. This exit code cannot be suppressed by zenzic:ignore, cannot be overridden by --exit-zero, and cannot be silenced by per-file ignore policies. The credential scanner (Z2xx codes) is active regardless of adapter mode, --offline flag, or --no-external flag.

Exit 3. A path traversal to an operating-system system directory was detected. This is a distinct severity class (security_incident) and represents the maximum security contract: the docs_dir configuration value or a scanned path attempted to escape the repository boundary toward system paths. Like Exit 2, it precedes all other exit-code evaluation. --exit-zero has no effect.

The evaluation order is fixed: Exit 3 conditions are checked first, Exit 2 second, Exit 1 third. This order ensures that security contracts are never shadowed by governance failures or score thresholds.

The four elements of the terminal interface analyzed in this article — the run header, the diagnostic block, the suppression ledger, and the exit code table — are not independent display decisions. They form a single interface that makes the documentation governance policy machine-readable, auditable, and deterministic.

A fail_under threshold, a suppression_cap, a per-category penalty model, and an immutable exit code contract are the formal encoding of what a team considers acceptable documentation quality. The terminal output is where that encoding is evaluated on every run. Treating it as display-only discards that evaluation. Treating it as a governance interface — machine-readable exit codes, auditable debt counters, caret-precise diagnostics — makes it enforceable at the pipeline boundary.

The Gate Paradox​

Before v0.8.0, the scoring engine had two separate tables: CODE_SARIF_LEVELS (used by the CI gate) and a penalty table (used by the DQS calculator). These tables were maintained independently. The invariant — that a CI-blocking code must also deduct from the score — was not enforced.

Three codes broke that invariant:

The observable consequence: a repository with 50 ORPHAN_LINK findings would fail the CI gate (exit code 1) but report a DQS of 100. The gate and the score were contradicting each other.

v0.8.0 established a single source of truth: CodeDefinition, a NamedTuple that stores severity, penalty, and category for each code in one place. CODE_SARIF_LEVELS is now derived from it. Structural registration is impossible without a penalty — the paradox cannot recur.

The three paradox codes received their penalties in the migration:

From Allowance to Flat-Cost​

The previous suppression model was allowance-based:

Suppressions up to suppression_cap were free. Only excess suppressions generated debt. The cap served two roles simultaneously: it was a governance allowance boundary and a hard-fail threshold.

That dual role was the problem. A project with suppression_cap = 30 and 30 active suppressions had: score impact = 0, exit code = 0. Suppressions were invisible in the DQS.

The v0.8.0 model decouples the two roles:

Every suppression deducts 1 point. The cap is exclusively a hard-fail threshold:

• When $n \leq \text{cap}$: score is reduced by $n$ points. Exit code is determined by the score gate.
• When $n > \text{cap}$: zenzic score exits with code 1 immediately, before score gate evaluation.

The Complete DQS Formula​

Assembling all five stages:

where $\mathcal{S} = \{Z201, Z202, Z203, Z204\}$, $n$ is the total active suppression count, and:

Or, expanding the full pipeline into a single expression:

where $\left| F_s \right|$ is the total suppression count and $\text{DebtCost} = 1$.

Numerical Properties​

Maximum achievable score is now $100 - n$, where $n$ is the active suppression count. A project with 10 suppressions cannot exceed 90, regardless of finding counts.

Monotonicity: $DQS$ is non-increasing in $n$. Adding a suppression never improves the score.

Score/gate coupling: the CI gate threshold (configured via --fail-under) and the hard-fail suppression threshold (suppression_cap) are now independent. A project with a score of 80 and 29 suppressions (cap = 30) passes both. A project with a score of 95 and 31 suppressions (cap = 30) fails the cap gate regardless of the score.

Closing the Mapping Gap​

The CodeDefinition single source of truth was established to prevent gate/score divergence. But the initial migration targeted only the three paradox codes (Z103, Z111, Z113). A subsequent audit identified four additional codes that the engine could emit (causing Exit 1) while carrying a penalty of 0.0 in the penalty table. The same paradox, at a smaller scale.

Three of the four received penalties in the migration:

The fourth — Z602 (I18N_PARITY) — remains frozen at 0.0 by architectural decision. I18N_PARITY acts as a governance gate: it enforces language parity between documentation trees and triggers Exit 1 when parity fails. Assigning it a DQS penalty would conflate two independent quality dimensions (translation completeness vs. link health / content quality) into a single number, making the score harder to interpret. A separate ADR is required to add Z602 to the DQS formula. For now, it is excluded from the penalty table, listed in FROZEN_CODES, and defined in CODE_DEFINITIONS with penalty 0.0.

Migration Impact (v0.7.x → v0.8.0)​

Projects with active suppressions will see their DQS decrease. The magnitude is exactly the active suppression count:

For a project with 10 suppressions previously scoring 75 (under allowance model with $n \leq \text{cap}$), the new score is $75 - 10 = 65$.

The suppression audit output in the CLI is unchanged. The label semantics for [MANAGED DEBT] and [EXTENDED DEBT] describe governance posture, not score exemption.

See Also​

• Scoring Algorithm Reference — Full formula derivation and penalty table
• Suppression Policy — Three suppression levels and the --audit override
• Finding Codes — Full Zxxx code encyclopedia with remediation steps

This page is the historical baseline for the v0.8.0 line. It intentionally preserves only the scope that was frozen for that milestone.

Baseline Scope (v0.8.0)​

The v0.8.0 baseline records the governance foundation used as bridge toward the next release line:

• strict-vs-score governance boundaries formalized for CI usage;
• sovereign audit usage documented as maintainers' inspection path;
• namespace stability contract documented for integration tooling;
• deterministic runtime constraints and security posture documentation hardened.

Historical Note​

Post-freeze work discovered during the epoch shift is intentionally excluded from this historical page and tracked in the v0.9.0 manifesto.

Compatibility Snapshot​

v0.8.0 remains a stable historical reference for contributors auditing legacy repository states and migration decisions.

This deep dive is for software architects and technical stakeholders who want to understand why architecture matters below the changelog line. The central claim of Zenzic is straightforward: zero-config should not mean zero-governance. It should mean deterministic defaults, explicit contracts, and interfaces that remain machine-readable under pressure.

The architecture came from five converging fronts: context fragmentation in complex repositories, dynamic-route ambiguity in static analysis, regex safety risk under adversarial inputs, deployment parity drift between local and CI, and governance blind spots that traditional SSG checks never model.

1) The Fragmentation Problem: When Context Stops Scaling​

The initial symptom looked small: architectural decisions became less reliable during long-lived maintenance sessions. As the instruction corpus and policy body grew, operational consistency dropped. Contributors would correctly apply one rule while violating another that had already been established in the same architectural cycle.

At first glance, this looked like a documentation quality issue. It was not. It was an information scalability issue.

The internal project specification corpus had grown into a dense operational memory: naming rules, historical exceptions, governance gates, invariants, release constraints, and adapter-level contracts. Human readers can often navigate this through intent and pattern recognition. Automation systems cannot guarantee stable retrieval under long, mixed-priority context.

The result was a class of subtle regressions:

• Correct syntax, wrong contract tier.
• Correct code, stale policy semantics.
• Correct diagnostics, incomplete provenance.

This forced a design decision. Instead of pushing more monolithic text into workflows, context was split into deterministic artifacts that can be requested on demand.

That decision had two outputs:

• Independent structural context tooling, for repository cartography.
• Zenzic JSON surfaces, as machine-facing truth exports for routes and codes.

In practice, this changes the operating model from "read everything, hope for retention" to "request only the contract you need, exactly when needed."

For deterministic automation workflows, this is decisive. Systems no longer parse long prose to infer architecture. They query canonical interfaces.

1.5) Shift-Left Metrics You Can Verify Yourself​

Performance claims are only useful if readers can reproduce them.

To verify Zenzic timing on your hardware, run the same checks locally and read the footer that Zenzic prints natively at the end of each run. The footer includes both elapsed duration and throughput.

Example footer:

standalone • 20 files (14 docs, 6 assets) • 0.8s • 38 files/s

Recommended sequence:

zenzic check references docs/
zenzic check links docs/
zenzic check all docs/

For each run, record:

• elapsed duration (0.8s field),
• throughput (38 files/s field),
• scanned file scope (file count and mode).

This provides a hardware-specific baseline without synthetic benchmarking.

2) Virtual Site Map and Reverse Mapping: Solving Dynamic Routes Without Running Node.js​

Dynamic routes are where traditional static linters lose clarity.

In Docusaurus, a route like /blog/tags/python/ may not correspond to a physical Markdown file. It is generated from frontmatter metadata spread across multiple source files. Likewise for paginated indexes and author pages. A filesystem-only linter sees no file, concludes "broken link," and emits false positives.

Build engines can resolve this because they execute generation logic. But that happens late, is expensive, and does not produce source-level diagnostics suited to pre-commit loops.

Zenzic resolves this using the Virtual Site Map (VSM) with reverse mapping invariants.

At a high level:

1. Parse source Markdown and adapter metadata.
2. Build canonical route entries, including generated virtual routes.
3. Require each virtual route to carry non-empty source_files provenance.
4. Reject route records that cannot be traced to physical origin.

This is not heuristic URL guessing. It is a contract.

# Simplified idea of the invariant
@dataclass(frozen=True)
class VirtualRoute:
    url: str
    source_files: frozenset[str]

    def __post_init__(self) -> None:
        if not self.source_files:
            raise ValueError("virtual route without provenance is invalid")

The pay-off is diagnostic quality. When a generated route fails, Zenzic can point to concrete source origins and frontmatter context instead of returning generic route-not-found output.

Example machine output:

zenzic inspect routes --json

{
  "route": "/blog/tags/python/",
  "kind": "tag",
  "status": "virtual",
  "source_files": [
    "blog/2026-05-01-v080-roadmap.mdx",
    "blog/2026-05-07-quartz-retrospective.mdx"
  ],
  "frontmatter_keys": ["tags", "slug", "authors"]
}

Now the error loop becomes actionable:

• you know the failing route,
• you know which files generate it,
• you know which frontmatter fields drive generation.

No Node.js execution is required to get this answer. That is the mathematical core of the Zenzic route model.

3) Security and ReDoS: The Incident Avoided by Design​

Every documentation scanner eventually faces regex complexity risk. The usual implementation path is Python's standard re module. It is convenient, familiar, and dangerous under adversarial patterns because catastrophic backtracking can explode runtime.

In a benign repository this may look harmless. In CI at scale, under untrusted or malformed content, this becomes a denial-of-service vector.

The architectural response treated this as a systems boundary problem, not a style refactor.

The Zenzic solution is an Anti-Corruption Layer (Facade) around regex operations. Contributors keep a simple internal API. The runtime backend is enforced to use RE2 semantics for linear-time matching where policy requires determinism.

# simplified facade pattern
from zenzic.core import regex


def contains_secret(line: str) -> bool:
    # contributor-facing API stays stable
    return regex.search(SECRET_PATTERN, line) is not None


# inside the facade implementation
# - compile through google-re2 backend
# - reject unsupported constructs at load time
# - expose a compatible API surface for callers

This design gives us three guarantees at once:

• Complexity bound: matching remains predictable, avoiding catastrophic backtracking classes.
• Policy enforcement: unsafe or unsupported patterns fail early at load/validation boundaries.
• DX continuity: contributors use one internal import path, not backend-specific code scattered across modules.

In architectural terms, the facade prevents dependency leakage. The domain model talks to a local contract; backend details stay behind the boundary. That is why security semantics can be hardened without destabilizing contributor workflows.

4) Four Gates in CI/CD: Security as a Supply Chain, Not a Single Check​

Many teams still treat documentation quality as a final build concern. Zenzic models it as a layered gate system where each stage narrows risk before it becomes expensive.

The gate model has four levels:

1. IDE Gate
2. Pre-Commit Gate
3. Pre-Push Gate
4. GitHub Actions Gate

The purpose is not duplication. The purpose is risk distribution.

• The IDE catches immediate authoring drift.
• Pre-commit blocks local bad states before history contamination.
• Pre-push enforces integration-level checks before remote divergence.
• GitHub Actions provides reproducible, shared enforcement at repository boundary.

The implementation hinge is the justfile. It is not a convenience wrapper; it is the parity contract.

# concept sketch
verify:
    uvx pre-commit run --all-files
    uvx nox -s tests
    uvx nox -s verify-codes-parity

When local and remote run the same orchestration surfaces, policy drift shrinks. This is Sovereign Parity: the same rules, same tooling strata, same exit semantics, regardless of execution location.

That matters for governance and auditability. A failed gate must mean the same thing everywhere, or the gate is procedural theater.

5) The Namespace Contract: Why Tier Boundaries Changed the System​

Before Zenzic, code families existed but ownership semantics were still easy to blur in real contribution flows. A policy rule could be discussed like a core invariant. A plugin rule could be treated like a frozen security guardrail.

The namespace contract was formalized to prevent that bleed.

• Core: engine invariants.
• Governance: project policy and lifecycle rules.
• Plugin: third-party extension surfaces.
• Custom: local project constraints.

This matters because suppression semantics and enforcement expectations are tier-dependent by design. Zenzic additionally formalizes immutable surfaces such as FROZEN_CODES, NON_SUPPRESSIBLE_CODES, and PLUGIN_FORBIDDEN_EXITS so that security findings cannot be casually reclassified into optional style noise.

Security findings are not suggestions. They are enforcement events.

5.5) Adapter Refactoring: From Protocol Flexibility to ABC Contracts​

v0.8.0 changed the adapter layer from permissive structural typing to explicit runtime contracts.

In the v0.7 line, adapter compliance relied on a Protocol surface plus runtime duck-typing checks. That model was flexible but late-failing: missing capabilities could escape until scan or validation paths were already running.

In v0.8, the contract is a concrete BaseAdapter Abstract Base Class with required abstract methods and factory-level subclass enforcement. Invalid adapter implementations now fail at instantiation time, not in mid-pipeline execution.

This refactor also applies Inversion of Control to the scanner boundary. The Core scanner no longer discovers engine details internally. Adapter context is resolved once by orchestration and injected as explicit callbacks and content roots, keeping the scanner engine-agnostic.

Logical flow:

BuildContext + repo_root
  -> get_adapter(...)
  -> inject adapter callbacks + discovered roots
  -> scanner/validator execute without engine discovery logic

MkDocs coverage was upgraded in the same cycle: multi-root discovery is now native in MkDocsAdapter, including recursive monorepo include traversal. Additional roots are mounted into the same VSM and reference-validation perimeter, so external docs trees no longer require manual wiring.

6) Eradicating Inline Noise: Directory Policies​

Every governance system eventually encounters a legitimate exemption problem. Brand-term checks are essential for catching stale references in active documentation. But release blogs are historical artifacts. Enforcing Z601 (obsolete brand term) against a blog post that intentionally names the old release identifier is not quality enforcement — it is false positive noise.

Before directory_policies, the only escape was an inline suppression comment scattered across every affected line:

<!-- zenzic:ignore: Z601 historical release -->
Quartz was the internal code name for v0.6.0.
<!-- zenzic:ignore: Z601 historical release -->
The Obsidian milestone closed the legacy adapter contract.

This approach accumulates debt. Inline suppressions count against the suppression_cap. Each file that writes its own inline escapes consumes one audit slot. At suppression_cap = 10, a fleet with many historical blog posts can exhaust the cap through legitimate exemptions, leaving no headroom for actual suppression abuse.

The structural fix introduced in v0.8.0 is directory_policies: a governance-level TOML contract that grants zero-debt exemptions to named path patterns.

[governance]
suppression_cap = 10
suppression_cap_fail_hard = true

[governance.directory_policies]
"blog/**"                         = ["Z601"]  # historical release posts: brand terms are intentional
"explanation/mineral-path.mdx"    = ["Z601"]  # SSOT codename registry (EN)
"it/explanation/mineral-path.mdx" = ["Z601"]  # SSOT codename registry (IT)

With this configuration in place, the blog posts become clean:

Quartz was the internal code name for v0.6.0.
The Obsidian milestone closed the legacy adapter contract.

No inline tags. No suppression comments. No debt. The policy exemption is declared once at the governance contract level, not repeated across every affected line.

When Zenzic applies a policy exemption during a standard scan, findings in those paths are dropped silently; the [POLICY_EXEMPTION] label is emitted only in --audit mode, giving reviewers a complete, centralized record of what was exempted and under which pattern. This preserves auditability without hiding the signal.

The hierarchy that emerges is deliberate:

1. Non-suppressible codes (NON_SUPPRESSIBLE_CODES) — security findings that cannot be overridden by any mechanism.
2. Directory policies — governance-level zero-debt exemptions declared in .zenzic.toml.
3. Inline suppressions — per-line escape hatches, counted against the cap and logged.

Zero-debt means the suppression cap is preserved for genuine edge cases, and the governance contract remains the authoritative source of intent.

Why This Is a Zero-Config Ecosystem, Not a Zero-Policy Tool​

Zero-config often gets misread as "minimal architecture." In Zenzic, zero-config means deterministic defaults with explicit contracts that remain inspectable.

That is why JSON inspection surfaces and tiered code contracts are first-class in the current architecture:

• They reduce ambiguity for humans.
• They reduce context burden for automation.
• They stabilize governance across contributors, integrations, and CI.

From an architectural perspective, Zenzic is less about adding checks and more about reducing interpretive entropy.

Closing Perspective​

The old mental model said: "if the site builds, documentation quality is acceptable."

Zenzic rejects that model.

A successful build can still hide leaked credentials, governance drift, unresolved virtual-route provenance, and policy regressions invisible to render pipelines. Build engines remain essential. They are just not sufficient as documentation integrity systems.

The system proves a different path:

• deterministic source-first analysis,
• machine-consumable architectural truth,
• linear-time security boundaries,
• and sovereign parity from local workstation to remote CI.

That is what a zero-config ecosystem looks like when engineering contracts are treated as public infrastructure, not internal folklore.

Italian version available in the Italian locale mirror of this article.

Source Integrity Before Build Integrity​

Build engines and static analyzers solve different phases of the problem:

• Build engines validate renderability after full site compilation.
• Zenzic validates source integrity before compilation.

Four hard facts​

Execution-time characteristics (architectural)​

Zenzic's analysis complexity is $O(N)$ in the number of files and links scanned. All pattern matching runs on the RE2 DFA engine, which guarantees linear time and is immune to catastrophic backtracking (ReDoS). There is no Node.js build-pipeline startup overhead for this pre-build analysis, but Python runtime dependencies must be installed (including RE2 bindings) and execution runs in the current Python process.

The phase difference relative to a full SSG build (which compiles, bundles, and emits routes) does not vary by environment — Zenzic always runs before the build engine is available.

The Namespace Contract​

Zenzic introduces an explicit tier model for findings and ownership.

Why frozen codes exist​

Security is not a style preference. It is a non-negotiable contract.

Zenzic formalizes frozen security semantics through immutable code surfaces such as:

• FROZEN_CODES
• NON_SUPPRESSIBLE_CODES
• PLUGIN_FORBIDDEN_EXITS

The practical implication is simple:

• Security findings like Z201 or Z204 are not optional suggestions.
• They cannot be downgraded into decorative warnings by local convenience flags.
• CI and local gates converge on the same enforcement semantics.

Open Ecosystem: JSON API Integration​

Zenzic exposes route truth as a machine interface:

zenzic inspect routes --json

This output is not presentation text. It is deterministic route metadata for automation.

External tools can consume this JSON directly:

• Independent structural analysis systems.
• Automation tools that need architectural context.
• CI orchestrators that require stable, typed diagnostics.

This removes fragile text scraping from the workflow. Tools consume contracts, not prose.

Bottom line​

The system closes a long-standing gap in documentation QA:

• Build validity is no longer mistaken for source integrity.
• Security is enforced as contract, not convention.
• Governance is explicit and testable.
• Virtual-route failures are traced to physical origin, not buried in generic 404 output.

That is the end of the SSG illusion.

Publication Decree: Sovereign Transition​

The Sovereign Transition is now formally declared as:

"The Sovereign Transition. Introducing Suppression CAP, Local Sanctuary, and Avion-Grade Governance."

The system is operational as fleet standard. The initial rollout dashboard can now be archived, and repository tagging proceeds under the new protocol.

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

This page defines what the Zenzic blog is for, what is published here, and how to use the content in daily documentation workflows.

Purpose​

The blog documents how to prevent documentation regressions before merge. The focus is operational:

• reduce production 404 risk from broken internal links,
• prevent credential leakage in public repositories,
• keep documentation quality gates deterministic in CI/CD.

Contents​

Posts are grouped into practical categories:

• Tutorials: step-by-step setup and first audit flows.
• Engineering: implementation details that affect integration behavior.
• Security: credential findings and remediation workflows.
• Governance: CI/CD policy patterns and suppression management.

Each article is expected to answer one concrete question and provide commands or configuration that can be applied immediately.

Usage​

Use this order if you are new:

1. Start with Tutorial: Get Started.
2. Apply the command to your repository.
3. Use tags in the sidebar to filter by problem type (security, governance, tutorials).
4. Subscribe to feeds for incremental updates:

• RSS: /blog/rss.xml
• Atom: /blog/atom.xml

If you need clarification on a workflow, use GitHub Discussions.