groundtruth-kb 0.6.1

Specification-driven governance toolkit for AI engineering teams

GroundTruth Knowledge DB

A specification-driven governance toolkit for AI engineering teams.

Track specifications, tests, work items, and architecture decisions with append-only versioning. Coordinate two AI agents (Prime Builder + Loyal Opposition) through a file-bridge protocol. Built for teams that need traceable, auditable engineering decisions.

New Here?

If you have never seen GroundTruth-KB before, start with docs/start-here.md. It assumes zero prior context and walks through everything from install to your first assertion on a Windows workstation with internet access.

Already a developer-preview adopter? Jump straight to:

• Day in the Life — a synthetic first week
• Evidence — live metrics, every row dated + pinned to a commit
• Known Limitations — open gaps, stated plainly
• Executive Overview — the business case

At a Glance

Capability	Description
Specifications	Decision log for what the system must do
Tests	Verify implementation meets specifications
Assertions	Continuously prove spec-implementation alignment
Work Items	Track gaps between specs and implementation
Deliberation Archive	Searchable decision history with rejected alternatives
Governance Gates	Pluggable enforcement at lifecycle transitions
File Bridge	Asynchronous two-agent review via versioned markdown

Tooling: CLI (gt), Web UI, Python API, project scaffolding, CI templates, process templates, dual-agent file bridge setup.

Quick Start

# Install from PyPI (Windows workstation with internet access)
pip install groundtruth-kb

# Create a project with scaffolding
gt project init my-project --profile local-only --no-seed-example --no-include-ci

# Verify workstation readiness
cd my-project
gt project doctor

Web UI (requires [web] extra):

pip install "groundtruth-kb[web]"
gt serve
# Visit http://localhost:8090

Same-day prototype (includes example data):

gt bootstrap-desktop my-prototype --owner "Your Organization" --init-git

See Start Here for the full walkthrough, including a PowerShell primer for readers who have never opened a terminal.

Architecture

flowchart TB
    L1["Layer 1<br/>Core Knowledge DB<br/>gt init / seed / assert / serve"]
    Bridge["Optional<br/>File Bridge Setup<br/>Prime Builder + Loyal Opposition"]
    L2["Layer 2<br/>Project Scaffold<br/>gt project init / upgrade"]
    L3["Layer 3<br/>Workstation Doctor<br/>gt project doctor"]
    Azure["Opt-in<br/>Azure readiness envelope<br/>specs, ADRs, checks, evidence"]

    L1 --> L2 --> L3
    Bridge --> L2
    L2 --> Azure
    L3 --> Azure

See docs/architecture/product-split.md for the authoritative layer definitions.

Why?

AI-powered systems change fast. Without traceable specifications and assertions, teams lose track of what was decided, why, and whether the implementation still matches. GroundTruth-KB provides the engineering discipline layer.

Status

This project is in early development (v0.6.0, developer-preview). The toolkit is extracted from a production system managing 2,000+ specifications and 11,000+ tests. See docs/known-limitations.md for current gaps.

Project scaffolding (gt project init), environment verification (gt project doctor), and scaffold upgrades (gt project upgrade) are available. Three profiles support different team configurations: local-only, dual-agent, and dual-agent-webapp.

Documentation

The method documentation describes the engineering discipline behind GroundTruth:

Guide	Topic
01 — Overview	Core workflow and governance model
02 — Specifications	Writing and managing specifications
03 — Testing	Test forms, outside-in testing, pipeline organization
04 — Work Items	Gap tracking, stage lifecycle, prioritization
05 — Governance	GOV specs, gates, assertions, protected behaviors
06 — Dual-Agent	Prime Builder + Loyal Opposition collaboration
07 — Sessions	Session IDs, wrap-up, audit cadence
08 — Architecture	ADR/DCL/IPR/CVR workflow
09 — Adoption	Upstream/downstream model, update procedures
10 — Tooling	CLI commands, web UI, Python API, configuration
11 — Operational Config	Bridges, automations, directives, roles
12 — File Bridge Automation	Durable file bridge polling, prompts, plugins, skills, and scheduler capture
13 — Deliberation Archive	Decision log with semantic search

Reference: Assertion Language | Azure Readiness Taxonomy | Desktop Setup | Example Project

Azure Readiness

GroundTruth-KB keeps the default scaffold lightweight, then adds an opt-in Azure enterprise readiness path for SaaS teams that need buyer-grade cloud evidence.

flowchart LR
    Starter["starter<br/>local-first default"]
    Candidate["production-candidate<br/>Azure decisions recorded"]
    Enterprise["enterprise-ready<br/>buyer evidence"]
    Regulated["regulated-enterprise<br/>industry controls"]

    Starter --> Candidate --> Enterprise --> Regulated

The full taxonomy is in docs/reference/azure-readiness-taxonomy.md. The wiki-ready summary lives at docs/wiki/azure-enterprise-readiness.md and is mirrored to the GitHub Wiki.

Process Templates

The templates/ directory contains reference templates for setting up a GroundTruth project: rules files, state files, hooks, and agent configuration, including a file bridge OS-poller setup prompt. Use gt project init my-project --profile <profile> for automated setup, or copy templates manually and customize the placeholders.

Contributing

See CONTRIBUTING.md for how to contribute. We especially value feedback about the engineering method itself — tag issues with method-feedback.

License

AGPL-3.0

---

© 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.