groundtruth-kb 0.3.1__tar.gz

groundtruth_kb-0.3.1/.editorconfig

@@ -0,0 +1,27 @@
+# EditorConfig — https://editorconfig.org
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

groundtruth_kb-0.3.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,69 @@
+name: Bug Report
+description: Report a bug in the GroundTruth Knowledge DB toolkit
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill out the fields
+        below so we can diagnose and fix the issue.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of the toolkit is affected?
+      options:
+        - Knowledge DB (db.py)
+        - Assertions engine (assertions.py)
+        - Web UI (app.py / templates)
+        - CLI / seed tooling
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened? Include error messages if applicable.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the issue.
+      placeholder: |
+        1. Install groundtruth-kb v0.1.0
+        2. Run `groundtruth init`
+        3. Insert a spec with ...
+        4. See error ...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "Output of `pip show groundtruth-kb | grep Version`"
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other context (screenshots, logs, environment details).
+    validations:
+      required: false

groundtruth_kb-0.3.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,50 @@
+name: Feature Request
+description: Suggest an improvement or new capability
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We value feedback that helps improve the engineering method behind
+        GroundTruth. Please describe the problem you're trying to solve and
+        the approach you have in mind.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: |
+        Describe the problem or limitation you encountered. Focus on the
+        "why" — what were you trying to accomplish and what got in the way?
+    validations:
+      required: true
+
+  - type: textarea
+    id: approach
+    attributes:
+      label: What approach do you suggest?
+      description: |
+        How would you solve this? Be as specific as you can. If you have
+        multiple approaches, list them with tradeoffs.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What alternatives did you consider?
+      description: Other approaches you thought about and why you didn't choose them.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: How broad is this change?
+      options:
+        - Small (single file / function)
+        - Medium (multiple files, same module)
+        - Large (cross-cutting, architecture-level)
+    validations:
+      required: true

groundtruth_kb-0.3.1/.github/copilot-instructions.md

@@ -0,0 +1,73 @@
+# Copilot Instructions — GroundTruth KB
+
+This project uses specification-driven governance. Every change must trace
+back to a specification or work item in the knowledge database.
+
+## Before writing code
+
+1. Read `CLAUDE.md` for project rules and workflow.
+2. Read `groundtruth.toml` for project configuration.
+3. If the assigned issue references a spec ID (e.g., SPEC-1234), that spec
+   defines the requirements. Do not add features beyond what the spec states.
+4. If no spec is referenced, implement only what the issue title and body
+   describe — nothing more.
+
+## Code standards
+
+- Python 3.11+. Lint with ruff (see `pyproject.toml` for rules).
+- All new files must include this copyright header as the first line:
+  ```python
+  # © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+  ```
+  For TypeScript/JavaScript files:
+  ```typescript
+  // © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+  ```
+- Every new function or class requires a test in `tests/`.
+- Do not add dependencies to `pyproject.toml` without explicit approval in
+  the issue body.
+- Do not modify `src/groundtruth_kb/db.py` schema without a spec reference.
+
+## What NOT to do
+
+- Do not create documentation files (*.md) unless the issue specifically
+  requests documentation.
+- Do not refactor code beyond what the issue requires.
+- Do not add type stubs, docstrings, or comments to files you did not change.
+- Do not modify `groundtruth.toml`, `groundtruth.db`, or any file in
+  `templates/` unless the issue explicitly targets those files.
+- Do not run `gt seed` or modify governance specs (GOV-*).
+
+## Commit messages
+
+Use this format:
+```
+<type>(<scope>): <description>
+
+Refs: <issue-number>
+```
+
+Types: `feat`, `fix`, `test`, `docs`, `chore`
+
+## PR description
+
+Include:
+- What changed and why (reference the issue)
+- Which files were modified
+- How to verify the change (test command or manual check)
+
+## Testing
+
+Run `python -m pytest tests/ -q` before requesting review. All existing
+tests must pass. New code must have new tests.
+
+## Architecture
+
+- `src/groundtruth_kb/` — core package (KB engine, CLI, assertions, gates)
+- `src/groundtruth_kb/project/` — project scaffold, doctor, upgrade
+- `src/groundtruth_kb/bridge/` — inter-agent bridge runtime
+- `templates/` — scaffold templates (bundled in wheel)
+- `tests/` — pytest test suite
+- `docs/` — method documentation
+
+Do not create new top-level directories or packages.

groundtruth_kb-0.3.1/.github/dependabot.yml

@@ -0,0 +1,27 @@
+# Dependabot dependency update configuration
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps):"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci):"

groundtruth_kb-0.3.1/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Problem
+
+<!-- What problem does this PR solve? Link to the issue if applicable. -->
+
+## Approach
+
+<!-- How does this PR solve the problem? Describe the implementation. -->
+
+## Rationale
+
+<!-- Why this approach over alternatives? What tradeoffs were considered? -->
+
+## Testing
+
+- [ ] Existing tests pass (`pytest`)
+- [ ] New tests added for new functionality
+- [ ] Assertions still pass (`groundtruth assert`)
+
+## Checklist
+
+- [ ] Code follows project conventions
+- [ ] No breaking changes to the public API
+- [ ] Documentation updated if needed

groundtruth_kb-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,web]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run tests
+        run: pytest -v --tb=short
+
+      - name: Wheel build + install smoke test
+        run: |
+          pip install build
+          python -m build --wheel
+          pip install --no-deps dist/*.whl --target /tmp/gt-wheel-smoke
+          PYTHONPATH=/tmp/gt-wheel-smoke python -c "
+          import groundtruth_kb
+          print(f'Version: {groundtruth_kb.__version__}')
+          tpl = groundtruth_kb.get_templates_dir()
+          print(f'Templates: {tpl}')
+          assert tpl.exists(), 'Templates must be packaged in wheel'
+          "
+
+  test-search:
+    runs-on: ubuntu-latest
+    name: "test (search / 3.12)"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies with search extra
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,web,search]"
+
+      - name: Run tests (including semantic search)
+        run: pytest -v --tb=short -k "deliberation"

groundtruth_kb-0.3.1/.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+# CodeQL analysis — GitHub's semantic code analysis for security vulnerabilities
+# Free for public repositories. Uploads findings to Security tab.
+#
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '17 4 * * 1'  # Weekly Monday 4:17 AM UTC
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze Python
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"

groundtruth_kb-0.3.1/.github/workflows/docs-check.yml

@@ -0,0 +1,53 @@
+# Documentation drift prevention — verifies CLI coverage, snippet correctness,
+# nav file references, version consistency, Python prereq, install tags,
+# ChromaDB message shape, and mkdocs build integrity.
+#
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+
+name: Docs Check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'templates/**'
+      - 'examples/**'
+      - 'README.md'
+      - 'pyproject.toml'
+      - 'src/groundtruth_kb/__init__.py'
+      - 'src/groundtruth_kb/cli.py'
+      - 'mkdocs.yml'
+      - 'scripts/check_docs_cli_coverage.py'
+      - '.github/workflows/docs-check.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'templates/**'
+      - 'examples/**'
+      - 'README.md'
+      - 'pyproject.toml'
+      - 'src/groundtruth_kb/__init__.py'
+      - 'src/groundtruth_kb/cli.py'
+      - 'mkdocs.yml'
+      - 'scripts/check_docs_cli_coverage.py'
+
+jobs:
+  docs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Check documentation drift
+        run: python scripts/check_docs_cli_coverage.py
+
+      - name: Build docs (strict mode)
+        run: mkdocs build --strict

groundtruth_kb-0.3.1/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+# Deploy documentation to GitHub Pages using mkdocs-material.
+# Requires: Settings > Pages > Source: GitHub Actions
+#
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

groundtruth_kb-0.3.1/.github/workflows/docstring-coverage.yml

@@ -0,0 +1,29 @@
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+name: Docstring Coverage
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  docstring-coverage:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check docstring coverage
+        run: interrogate src/groundtruth_kb/ --fail-under 50 -vv

groundtruth_kb-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,88 @@
+# Build, verify, and publish groundtruth-kb.
+#
+# Install from PyPI:
+#   pip install groundtruth-kb
+#
+# Install from GitHub (pinned version):
+#   pip install "groundtruth-kb @ git+https://github.com/Remaker-Digital/groundtruth-kb.git@v0.3.0"
+#
+# This workflow runs on Release creation to:
+#   1. Build and verify the wheel
+#   2. Attach artifacts to the GitHub Release
+#   3. Publish to PyPI via Trusted Publishers (OIDC)
+#
+# Copyright (c) 2026 Remaker Digital. Licensed under AGPL-3.0-or-later.
+
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-verify:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Verify distribution
+        run: twine check dist/*
+
+      - name: Smoke test — install built wheel
+        run: |
+          pip install --no-deps dist/*.whl --target /tmp/gt-smoke
+          PYTHONPATH=/tmp/gt-smoke python -c "
+          import groundtruth_kb
+          print(f'Version: {groundtruth_kb.__version__}')
+          print(f'Templates: {groundtruth_kb.get_templates_dir()}')
+          assert groundtruth_kb.__version__, 'Version must be set'
+          assert groundtruth_kb.get_templates_dir().exists(), 'Templates must be packaged'
+          "
+
+      - name: Smoke test — install from GitHub ref
+        run: |
+          pip install --target /tmp/gt-github-smoke "groundtruth-kb @ git+https://github.com/${{ github.repository }}.git@${{ github.ref_name }}"
+          PYTHONPATH=/tmp/gt-github-smoke python -c "import groundtruth_kb; print(f'GitHub install OK: {groundtruth_kb.__version__}')"
+
+      - name: Attach artifacts to release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          for f in dist/*; do
+            gh release upload "${{ github.event.release.tag_name }}" "$f" --clobber
+          done
+
+      - name: Upload artifacts for publish job
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build-verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download built artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

groundtruth_kb-0.3.1/.github/workflows/security.yml

@@ -0,0 +1,76 @@
+# Security scanning — Semgrep SAST + pip-audit dependency check
+# Runs on every PR and push to main. Uploads SARIF to GitHub Code Scanning.
+#
+# © 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.
+
+name: Security
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'requirements*.txt'
+  push:
+    branches: [main, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  semgrep:
+    name: Semgrep SAST
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Semgrep
+        uses: returntocorp/semgrep-action@v1
+        with:
+          config: >-
+            p/python
+            p/security-audit
+            p/secrets
+          generateSarif: "1"
+
+      - name: Upload SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: semgrep.sarif
+          category: semgrep
+
+  pip-audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install package
+        run: pip install -e ".[dev,web]"
+
+      - name: Run pip-audit
+        run: |
+          pip install pip-audit
+          mkdir -p .quality
+          # PYSEC-2022-42969: py 1.11.0 py.path.svnwc vulnerability — not exploitable
+          # in our usage (transitive dep from CI runner, not imported by our code).
+          pip-audit --ignore-vuln PYSEC-2022-42969 --format=json --output=.quality/pip-audit.json || true
+          pip-audit --ignore-vuln PYSEC-2022-42969 --format=cyclonedx-json --output=.quality/sbom.json || true
+          pip-audit --ignore-vuln PYSEC-2022-42969
+        continue-on-error: false
+
+      - name: Upload audit results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: pip-audit-results
+          path: .quality/