ADR: Public-Facing Entity Integrity, Portal Link Rot Sentinel & Canonical Install Dispatcher
Context
During public adoption readiness evaluation for release v0.3.5, deep inspection of public-facing endpoints and documentation revealed two critical integrity defects:
- Workstation Path & Scheme Leakage: LLM prompt formatting instructions previously resulted in 371
file:///Users/<developer>/...URI links leaking into 45 markdown guides and generated HTML documents. The existing link-checker (scripts/open-core/check-doc-links.sh) inadvertently permitted/Users/*paths rather than failing closed. - Symlink Failure on Raw GitHub Distribution: The repository root
install.shwas maintained as a symbolic link pointing toscripts/install.sh. When community operators executedcurl -fsSL https://zqk.dev/install.sh | bash(redirected by Cloudflare tohttps://raw.githubusercontent.com/zqk-os/zqk/main/install.sh), GitHub's raw file server returned the literal ASCII string"scripts/install.sh"rather than following the symlink, causing client-side script execution to fail immediately withNo such file or directory.
Decision
- Canonical Regular File Distribution for Root Installers:
- The root
install.shis codified as a regular POSIX executable file (0755) identical byte-for-byte toscripts/install.sh, eliminating reliance on symlink resolution across raw HTTP content mirrors and public endpoints (https://zqk.dev/install.sh). - Zero-Tolerance Fail-Closed Link Sentinel:
-
scripts/open-core/check-doc-links.shis upgraded to immediately flag anyfile://URI scheme or workstation path (/Users/,/home/,/private/var/) as a fatal validation error. -scripts/open-core/docs-portal/generate_docs_portal.pyenforces automated normalization of workspace markers (/zqk-public-candidate/,/zqk/,/zqke/) to canonical relative documentation paths or GitHub repository blob references (https://github.com/zqk-os/zqk/blob/main/...). - Three-Fold Proof Test Governance (
pkg/community/link_sentinel_test.go): - Static Floor Invariant (TestLinkSentinel_StaticFloorInvariant): Crawls all markdown files underdocs/asserting 0 leaked developer usernames (/Users/<developer>), 0file://link targets, and verifiesinstall.shis a non-symlink regular file matchingscripts/install.sh. - Operational Dynamic Proof (TestLinkSentinel_OperationalDynamicProof): Runscheck-doc-links.shagainst the entire codebase verifying 100% clean link resolution across all articles. - Negative Adversarial Boundary (TestLinkSentinel_NegativeAdversarialBoundary): Injects adversarial documents containing leaked developer workstation paths and asserts fail-closed termination. - Mandatory Documentation Portal Synchronous Deployment:
- Documentation portal assets are compiled and published directly to
zqk-os/zqk-docs(docs.zqk.dev) with zero workstation leaks or unresolvable URI artifacts.
Status
Accepted and verified for Cycle 98 (Public-Facing Entity Integrity & Portal Link Sentinel).