CLI ZQK-Shim Traceability & Cryptographic Provenance Guide

Overview

The ZQK Shim (cmd/zqk-shim) provides a transparent, low-latency binary interceptor for developer workflows involving git and gh. When positioned ahead of genuine system executables on PATH (such as ~/.zqk/shims or project-local shim directories), zqk-shim provides four core operational guarantees:

  1. Infinite-Loop-Free System Binary Resolution: Locates the underlying Genuine system binary while safely skipping the shim directory itself.
  2. Bidirectional Workstream Traceability Enforcement: Intercepts mutating operations (git commit, gh pr create) to ensure active branches are strictly tied to active workstream contracts in the Knowledge Kernel.
  3. Cryptographic Agent Provenance Attestation: Signs pull requests using Ed25519 project seating credentials (or SHA-256 fallbacks) and injects verifiable agent provenance stamps into PR bodies.
  4. Interactive CLI Proxying with Break-Glass Telemetry: Seamlessly proxies interactive and automated terminal sessions via pkg/specbuilder/cli_builders, providing fail-closed break-glass override mechanics.

Architectural Taxonomy & Core Components

cmd/zqk-shim/
β”œβ”€β”€ main.go                          # Interception engine, traceability gates, & crypto stamping
β”œβ”€β”€ main_test.go                     # Unit tests for bypass, mutations, and break-glass checks
β”œβ”€β”€ shim_coverage_elevation_test.go  # Isolated git repository, CAS workstream, & edge-case tests
β”œβ”€β”€ e2e_test.go                      # End-to-end process execution & stdout/stderr interception
└── README.md                        # Quickstart documentation and PATH configuration

1. Binary Interception & Execution Lifecycle

[Developer / Agent Command: git commit / gh pr create]
                         β”‚
                         β–Ό
             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
             β”‚       runShim         β”‚
             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                         β”‚
         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
         β–Ό                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  findRealBinary  β”‚           β”‚isMutatingOp(cmd) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚ (found real path)             β”‚ (true for commit/pr)
         β–Ό                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Check Bypass Env │◄─────────── validateCommitTraceabilityWithEnv  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚                               β”‚
         β”‚ (if bypass, require >=30 char)β”‚ (must match active workstream)
         β–Ό                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Inject Crypto PR β”‚           β”‚   Proceed with Executable Spec     β”‚
β”‚   Body Stamp     β”‚           β”‚   via pkg/specbuilder/cli_builders β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚                                       β”‚
         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                         β”‚
                         β–Ό
             [Genuine Binary Execution]

Path Resolution (findRealBinary)

findRealBinary inspects os.Getenv("PATH") across OS-specific path separators. It determines the location of the current shim using fileutil.Executable() and deliberately ignores any matching binary located within that directory. If no genuine executable exists elsewhere on PATH, the shim logs a diagnostic error and exits with code 1, preventing runaway execution loops.


2. Commit & PR Traceability Gate

The Bidirectional Traceability Contract

To maintain pristine graph integrity within the ZQK Knowledge Kernel, mutating source control actions must be explicitly traceable to authorized workstream objects:

  • Target Commands: Mutating operations include git commit and gh pr create. Non-mutating commands (git status, git diff, git log, gh pr list, gh pr view) pass through unhindered.
  • Branch Matching: The active Git branch (retrieved via git rev-parse --abbrev-ref HEAD) must match an active workstream identifier (e.g. WS-STARTER-COMMUNITY-001 or integration/ws-starter-community-001).
  • Storage Verification: The shim reads from the project's CAS object storage via pkg/storage, querying KindWorkstream records whose status is strictly active.

Fail-Closed Break-Glass Override (hasBreakGlassOverride)

In emergency production scenarios or critical air-gapped hotfixes, traceability checks can be bypassed:

  • Environment variable: SHIM_BYPASS_TRACEABILITY=1 or ZQK_SHIM_BYPASS_TRACEABILITY=1.
  • Mandatory Justification Constraint: The bypass will fail closed with code 1 unless accompanied by an explicit, auditable break-glass reason via BREAK_GLASS_REASON or ZQK_BREAK_GLASS_REASON.
  • Minimum Length Invariant: The justification must contain at least 30 characters (minBreakGlassReasonLen = 30), ensuring sufficient context is recorded for compliance audit trails.

3. Cryptographic Provenance & Agent Stamping

Provenance Stamp Architecture

When creating pull requests via gh pr create, zqk-shim generates a cryptographic stamp proving the identity of the executing agent or contributor:

  1. Seating Key Resolution (resolveTrustedAgentPrivateKey): - Discovers project-level seating credentials stored in .zqk/credentials/agent_seating.json. - Reads private signing keys via pkg/authcred.AgentSeatingCredential. - Validates that the active agent identity possesses valid RBAC permissions.
  2. Ed25519 Cryptographic Signatures: - Hashes project commit metadata and current branch state. - Signs the state digest using Ed25519 private keys. - Formats the signature as a verifiable hex payload: [ZQK_AGENT_STAMP: <hex_encoded_signature>]

  3. Fallback & Degradation Handling: - If no private key is present (e.g., untrusted ambient environment), the shim computes a deterministic SHA-256 fingerprint from the repository state. - If agent identity is not declared, it falls back to anonymous-agent provenance.

Body Injection (injectPRBodyStamp)

injectPRBodyStamp parses the argument stream of gh pr create:

  • Appends the stamp to existing --body <text> or -b <text> arguments.
  • If no body flag exists, injects --body "[ZQK_AGENT_STAMP: <hex>]".
  • Preserves all other command flags and interactive arguments untouched.

4. Verification & Test Suite

The cmd/zqk-shim package is verified to 94.2% statement coverage across three dedicated test suites:

Test File Focus & Verification Domain
main_test.go Unit verification of mutation flags, break-glass length checks, and private key resolution.
shim_coverage_elevation_test.go Isolated Git repository creation, CAS workstream matching, path traversal, and edge cases.
e2e_test.go End-to-end binary execution, stdout/stderr streaming, and simulated command interception.

All tests comply with fail-closed kernel constraints and pass automated verification under TST-001.