Continuous Source Verification Matrix (CSVM) Specification
1. Executive Summary & Core Philosophy
The Continuous Source Verification Matrix (CSVM) provides universal, file-level quality and architectural invariant tracking across all source code and project artifacts in ZQK.
Unlike transient, prompt-promiscuous chat harnesses that forget criteria across iterations, the CSVM couples:
- Content-Addressable Verification (
evidence_sha): Every file is tracked by its SHA-256 hash. Once a file passes an evaluation dimension, its status is stamped and cached. Clean files achieve \(O(1)\) instant skips (0 ms, 0 tokens) on future runs until their content hash changes. - Standard Evaluation Dimension Codes: Homogeneous check suites codified directly in the Knowledge Kernel:
-
HCODE: Hardcoded Logic, Magic Literals, Raw Permissions, Fixed Paths, and Static Versions. -EFFPERF: Efficiency, Complexity, Resource Hygiene, Context Deadlines. -ERRHYG: Error Hygiene, Wrapping, and Fail-Closed Resilience. -CONCURR: Named Goroutines (goroutinelabels), Lifecycle Termination, Deadlock Safety. -SECOBS: Zero-PII, Secret Eradication, and Structured Logging. -DOCSIG: API Contracts and 100% Exported Symbol GoDoc Coverage. - Programmatic Writer Gating: The matrix ledger cannot be manually edited by agents or users. All updates must be stamped programmatically via
zqk matrix stampor evaluated viazqk matrix verify, verified against the target file's content hash. - Decoupled 3-Party Quality Loop: - Blind Sensor (Evaluator Agent / Czar): Scans source files and extracts raw structured findings (line, count, category, literal value) without knowing acceptance thresholds. - Policy Engine (Central Matrix): Invisibly scores findings against authoritative thresholds, maintains the Global String Literal Inventory, and computes Diamond Scores (1 to 5 diamonds). - Fixer Agent: Remediates flagged violations using structured sensor findings, refactoring code and submitting it for re-evaluation.
2. Kernel Policy & Persona Traceability
| Dimension / Policy | Kernel Object ID | Enforcement | Status |
|---|---|---|---|
| Hardcoding Eradication Czar | PER-HARDCODING-ERADICATION-CZAR |
Adversarial Sensor | Approved |
| HCODE Dimension | POL-CODE-1791593579304410000-e749bb5f |
Automated / Critical | Active |
| EFFPERF Dimension | POL-CODE-1791593697272400000-9b0f833b |
Automated / High | Active |
| ERRHYG Dimension | POL-CODE-1791593699894406000-cd6f25fd |
Automated / High | Active |
| CONCURR Dimension | POL-CODE-1791593703788100000-9f2dff69 |
Automated / Critical | Active |
| SECOBS Dimension | POL-CODE-1791593707127249000-965eda9e |
Automated / Critical | Active |
| DOCSIG Dimension | POL-CODE-1791593709986529000-029390e6 |
Automated / Medium | Active |
| Programmatic Writer Policy | POL-CODE-1791593713535339000-77a9d462 |
Automated / Critical | Active |
| Blind Evaluation Policy | POL-CODE-1791593716794368000-efa51192 |
Automated / High | Active |
3. Global String Literal Deduplication Engine
To eliminate rampant hardcoding while accommodating legitimate, unique log statements and messages:
- Every string literal found in source files is indexed alphabetically in
.zqk/literal_inventory.json. - Tolerance Rule: Exactly 1 unique occurrence of a string literal is tolerated globally across the codebase.
- Violation Threshold: If an identical string literal appears \(\ge 2\) times across different call sites or files without being declared as a shared package constant, it triggers an immediate deduplication failure.
4. Diamond Scoring Rubric (1-5 Diamonds)
- ◆◆◆◆◆ (5 Diamonds - Flawless): 0 violations, clean invariant adherence, optimal documentation.
- ◆◆◆◆◇ (4 Diamonds - Minor Polish): 0 critical/high violations; \(\le 2\) minor notices (e.g. single-use log string without deduplication threat).
- ◆◆◆◇◇ (3 Diamonds - Pass with Remediation Backlog): Minor issues present, non-blocking for local development, blocking for production release.
- ◆◆◇◇◇ (2 Diamonds - Failing): 1 or more high violations (e.g. raw permissions, missing context timeout).
- ◆◇◇◇◇ (1 Diamond - Critical Failure): Critical violations (e.g. hardcoded release version, naked goroutine, hardcoded secret, swallowed error).
5. Universal Multi-Language Configuration (.matrix.yaml)
To ensure portability across any repository, language, or ecosystem without hardcoding host-language ASTs, the engine is configured via a declarative .matrix.yaml profile:
version: 1
matrix:
name: source_code_verification
dimensions:
- code: HCODE
name: Hardcoded Logic and Literal Eradication
severity: critical
- code: EFFPERF
name: Efficiency and Resource Hygiene
severity: high
- code: ERRHYG
name: Error Hygiene and Resilience
severity: high
- code: SECOBS
name: Zero-PII and Structured Observability
severity: critical
- code: DOCSIG
name: Contracts and Documentation
severity: medium
classes:
source_code:
match: ["**/*.py", "**/*.ts", "**/*.go", "**/*.rs", "**/*.java", "**/*.c", "**/*.cpp"]
exclude: ["**/vendor/**", "**/node_modules/**", "**/*_test.*", "**/test_*.py"]
checks:
- dimension: HCODE
type: pattern
rules: [no_user_home_paths, no_raw_permissions, no_release_tags, no_hardcoded_secrets]
- dimension: SECOBS
type: pattern
rules: [no_private_keys, no_hardcoded_tokens]
test_code:
match: ["**/*_test.go", "**/*.test.ts", "**/test_*.py", "**/tests/**"]
checks:
- dimension: SECOBS
type: pattern
rules: [no_hardcoded_tokens]
documentation:
match: ["**/*.md", "**/*.rst", "docs/**"]
checks:
- dimension: DOCSIG
type: command
command: "markdownlint --config .markdownlint.yaml {file}"
ledger:
path: .zqk/quality/matrix_cache.json
algorithm: sha256
Pluggable Check Primitives
pattern: Declarative regex and literal string analysis running in pure text space without AST compiler bindings.command: Spawns an external command or linter (eslint,ruff,cargo clippy,golangci-lint) and maps return codes/stdout to findings.agent: Passes file content and evaluation rubrics to adversarial LLM agents returning structured diamond scores.
Ecosystem Decoupling & Optional Adapters
The matrix engine produces standard, self-contained JSON and Markdown scorecards. Optional adapters (e.g. --adapter zqk) bridge findings to host platforms (such as minting ZQK Knowledge Kernel technical_debt or backlog_item objects) without contaminating the core engine with enterprise or kernel dependencies.