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:

  1. 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.
  2. 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.
  3. Programmatic Writer Gating: The matrix ledger cannot be manually edited by agents or users. All updates must be stamped programmatically via zqk matrix stamp or evaluated via zqk matrix verify, verified against the target file's content hash.
  4. 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:

  1. Every string literal found in source files is indexed alphabetically in .zqk/literal_inventory.json.
  2. Tolerance Rule: Exactly 1 unique occurrence of a string literal is tolerated globally across the codebase.
  3. 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

  1. pattern: Declarative regex and literal string analysis running in pure text space without AST compiler bindings.
  2. command: Spawns an external command or linter (eslint, ruff, cargo clippy, golangci-lint) and maps return codes/stdout to findings.
  3. 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.