Local CI & Precommit Verification Governance Guide (zqk ci & zqk precommit)

1. Overview & System Mission

The ZQK Knowledge Kernel enforces fail-closed safety, invariant gate compliance, and strict code quality before commits can enter source control or integration branches. Two dedicated command groups govern pre-flight validation and local isolated test execution:

  1. Local CI Engine (zqk ci): Manages isolated staging workdirs (.zqk/local-ci/), executes test cases against specific commit hashes or working trees (zqk ci checkout, zqk ci run), provides inspectable status (zqk ci status), and cleanly cleans up staging trees (zqk ci demote).
  2. Precommit Gate Verification (zqk precommit): Enforces pre-commit invariants across categorized checks (lint, policy, integrity, ast), records incremental results (zqk precommit write-result), aggregates verdicts (zqk precommit aggregate), renders diagnostic reports, and verifies that commits only proceed when all gates pass (zqk precommit status).

1.1 Architecture & Workflow Diagram

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        LOCAL CI & PRECOMMIT GOVERNANCE ARCHITECTURE                    │
│                                                                                        │
│  Git Hook Execution                       Precommit Verification Matrix                │
│ ┌────────────────────────┐              ┌─────────────────────────────┐                │
│ │ git commit             │ ───────────► │ - lint (zqk-vet / golangci) │                │
│ └────────────────────────┘              │ - policy (DSL compliance)   │                │
│                                         │ - integrity (CAS/specs)     │                │
│                                         │ - ast (zero-violation)      │                │
│                                         └──────────────┬──────────────┘                │
│                                                        ▼                               │
│                                         ┌─────────────────────────────┐                │
│                                         │ zqk precommit aggregate     │                │
│                                         │ Result: Block / Allow       │                │
│                                         └─────────────────────────────┘                │
│                                                                                        │
│  Isolated Staging Pipeline                Local CI Engine                              │
│ ┌────────────────────────┐              ┌─────────────────────────────┐                │
│ │ zqk ci checkout --sha  │ ───────────► │ Target: .zqk/local-ci/      │                │
│ └────────────────────────┘              │ Sandbox Workdir Isolation   │                │
│                                         │ Test Suite Execution        │                │
│                                         └─────────────────────────────┘                │
└────────────────────────────────────────────────────────────────────────────────────────┘

2. Local CI Engine (zqk ci)

2.1 Basic Usage & Subcommands

# Check status of local CI workdir and recorded SHA
zqk ci status

# Check out a target SHA into the isolated local CI sandbox
zqk ci checkout --sha <commit-sha>

# Execute local CI test suites within the sandboxed environment
zqk ci run

# Execute checkout only without triggering the full test suite
zqk ci run --checkout-only

# Demote/clean local CI sandbox artifacts
zqk ci demote

2.2 Operational Behavior

  • Sandboxed Directory: Operates within .zqk/local-ci/workdir, ensuring that tests run in an isolated environment without mutating active developer state.
  • Fail-Closed Root Resolution: Uses project-aware context resolution (cli.GetContext(cmd)) falling back to root discovery.
  • SHA Tracking: Persists SOURCE_SHA in the local CI root to trace which commit state was checked out and evaluated.

3. Precommit Gate Governance (zqk precommit)

3.1 Subcommand Hierarchy

  • zqk precommit status: Displays current precommit verdict (Allowed / Blocked), listing all blocking categories and check summaries.
  • zqk precommit aggregate: Aggregates category results into the master .zqk/state/precommit.json summary.
  • zqk precommit write-result: Records a structured category verdict (--category, --ok, --summary, --blocking, --details).
  • zqk precommit write-result-from-last: Ingests staged output from category tools and aggregates verdicts.
  • zqk precommit clear: Clears recorded category verdicts to reset precommit state.
  • Diagnostic Reports:
  • zqk precommit lint-report: Displays latest lint check diagnostics.
  • zqk precommit policy-report: Displays latest policy compliance diagnostics.
  • zqk precommit integrity-report: Displays CAS and spec integrity diagnostics.

3.2 Gate Invariant Lifecycle

[Tool Run] ──► [write-result --category <cat> --ok=<bool>] ──► [aggregate] ──► [status check]

If any category with --blocking=true reports ok=false, zqk precommit status returns Block: true and prevents git commit from proceeding.


4. Verification & Testing

Both cmd/zqk/ci and cmd/zqk/precommit maintain >=80.0% statement test coverage with comprehensive unit and CLI execution tests:

  • cmd/zqk/ci/ci_cmd_test.go: Validates subcommand hierarchy, clean and configured status checks, demote lifecycle, missing root handling, and checkout flags.
  • cmd/zqk/precommit/precommit_cli_test.go: Validates category writes, last-result ingestion, aggregation, status blocking verdicts, and diagnostic reports.