Z108 STALE_ALLOWLIST_ENTRY (config hygiene check)

[PythonWoods-Dev]

Context

EPOCH 6 (v0.7.0 "Quartz Maturity") introduced [link_validation].absolute_path_allowlist as a declarative trust contract between Docusaurus instances (see ADR-0011 "Cross-Instance Allowlist").

The natural follow-up — Z108 STALE_ALLOWLIST_ENTRY — would warn when an allowlist prefix no longer matches any real link in the corpus, preventing the contract from rotting silently as routes are renamed or removed.

This issue tracks the deferred work, recorded in the Technical Debt Ledger at v0.7.0 ship time.

Why deferred (not declined)

Implementing Z108 inside validator.py (the per-link validator) would violate Pillar 3 — Pure Functions by introducing shared mutable state across the scan: each link check would need to mark its matching allowlist entry as "used", then a final pass would inspect leftovers.

Pure-function constraint is non-negotiable for the Core: it underpins thread-safety, determinism, and the adaptive parallelism contract (ADAPTIVE_PARALLEL_THRESHOLD).

Proposed home — zenzic inspect config

The correct architectural home for stale-entry detection is a separate read-only inspection command:

zenzic inspect config           # read-only audit of zenzic.toml
zenzic inspect config --strict  # exit 1 on any stale entry (CI-friendly)

Characteristics:

• Reads zenzic.toml once, walks the corpus once, joins.
• No coupling to the per-link validator; no shared state across the scan.
• Naturally extensible to other config-hygiene checks (orphan rule overrides, unused suppression categories, …).

Acceptance criteria (v0.8.0 "Basalt")

• New command zenzic inspect config (read-only, exit 0 by default, exit 1 with --strict).
• Z108 finding emitted for each absolute_path_allowlist entry that matches zero in-corpus links.
• Documentation: developers/reference/cli.mdx (EN+IT) + docs/reference/configuration.mdx#z108 (EN+IT).
• Tests: at least one happy-path ("all entries used") and one stale-entry case + a Team-D adversarial test (entry whose prefix only matches an externally-linked path that lives outside the scanned roots).
• Technical-debt ledger entry closed (status: resolved, link to merged PR).

References

• ADR-0011 Cross-Instance Allowlist — Suppression vs Configuration section
• zenzic-doc/developers/governance/technical-debt.mdx (Z108 entry)
• v0.7.0 RELEASE.md → "EPOCH 6 — Cross-Instance Trust Sovereignty" → "Z108 deferred to v0.8.0 — by design"

---

Milestone v0.8.0 "Basalt". Pillar 3 compliant by construction.