vouch-kb 0.1.0__tar.gz

vouch_kb-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: vouch did something it shouldn't
+labels: bug
+---
+
+## What happened
+
+<!-- One sentence: what went wrong. -->
+
+## What you expected
+
+<!-- One sentence: what should have happened. -->
+
+## Reproduction
+
+<!-- Minimum sequence to reproduce. Ideally a shell transcript. -->
+
+```bash
+$ vouch ...
+```
+
+## Environment
+
+- vouch version: `vouch --version`
+- Python version: `python3 --version`
+- OS:
+- Host (Claude Code / Cursor / Codex / standalone CLI / something else):
+
+## `.vouch/` state
+
+<!-- If relevant, paste the output of `vouch doctor`. Redact anything
+     sensitive. -->
+
+```
+$ vouch doctor
+```
+
+## Anything else
+
+<!-- Logs, stderr, hypotheses, what you tried. -->

vouch_kb-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issue
+    url: https://github.com/plind-junior/vouch/security/advisories/new
+    about: Please report security issues privately via GitHub Security Advisories, not as a public issue. See SECURITY.md.
+  - name: Question
+    url: https://github.com/plind-junior/vouch/discussions
+    about: General questions, ideas, and discussions belong in Discussions, not Issues.

vouch_kb-0.1.0/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: An idea for something vouch should do
+labels: enhancement
+---
+
+## What you're trying to do
+
+<!-- Describe the problem from your seat. "When I'm doing X, I want
+     to Y, because Z." Concrete examples help. -->
+
+## What you've tried
+
+<!-- Existing vouch features you tried; why they didn't fit. -->
+
+## Suggested shape
+
+<!-- If you have one. A method name, a CLI flag, a config option.
+     "Add `vouch foo` that does bar" is fine. -->
+
+## Compatibility considerations
+
+<!-- Would this break existing KBs? Would it require a VEP (surface
+     change), or is it additive? -->
+
+## Alternatives
+
+<!-- Other ways the same problem could be solved. -->

vouch_kb-0.1.0/.github/ISSUE_TEMPLATE/vep.md

@@ -0,0 +1,37 @@
+---
+name: VEP intent (before writing a full proposal)
+about: Float a surface change before drafting a VEP
+labels: vep, design
+---
+
+<!-- This issue is for socialising a surface-level idea before you sit
+     down to write a full VEP. If you already know what you want and
+     are ready to write the doc, skip this and open a PR adding
+     proposals/VEP-NNNN-your-slug.md directly. -->
+
+## What part of the surface
+
+<!-- Tick all that apply. -->
+
+- [ ] Object model (Source/Claim/Page/Entity/Relation/Evidence/Proposal/Session/AuditEvent)
+- [ ] `kb.*` method surface
+- [ ] On-disk layout under `.vouch/`
+- [ ] Bundle format
+- [ ] Audit-log shape
+- [ ] `config.yaml` defaults
+- [ ] New transport
+
+## Sketch
+
+<!-- 3-5 sentences. Just enough that a maintainer can tell whether
+     it's worth a full VEP. -->
+
+## Use case
+
+<!-- What user task does this enable? Or what user pain does it
+     solve? -->
+
+## What you're unsure about
+
+<!-- Open questions. The maintainers will weigh in before you invest
+     in a full VEP. -->

vouch_kb-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+<!--
+Thanks for sending a PR! Before opening, please skim CONTRIBUTING.md.
+
+Surface changes (object model, kb.* methods, on-disk layout, bundle
+format, audit-log shape) need a VEP first; see proposals/README.md.
+-->
+
+## What changed
+
+<!-- One paragraph. The *what*, briefly. -->
+
+## Why
+
+<!-- One paragraph. The *why* — what problem this solves, what it
+     enables, or what it fixes. Link the issue if any. -->
+
+## What might break
+
+<!-- Be honest. For users with an existing .vouch/ directory:
+     - Will any file move?
+     - Will any field on disk change shape?
+     - Will any kb.* method behave differently?
+     If yes to anything, flag it as a breaking change. -->
+
+## VEP
+
+<!-- If this is a surface change, link the accepted VEP here.
+     If you're not sure whether you needed one, ask. -->
+
+## Tests
+
+- [ ] `make check` passes locally (lint + mypy + pytest)
+- [ ] New / changed behaviour has a test
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`

vouch_kb-0.1.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "chore"
+      include: scope
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    labels: ["dependencies", "ci"]
+    commit-message:
+      prefix: "chore"
+      include: scope

vouch_kb-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: lint
+        run: python -m ruff check src tests
+
+      - name: type
+        run: python -m mypy src
+
+      - name: test
+        run: python -m pytest --cov=vouch --cov-report=xml
+
+      - name: upload coverage
+        if: matrix.python == '3.12'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage
+          path: coverage.xml
+
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: upload artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/

vouch_kb-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: release
+
+# Publish to PyPI on a version tag (e.g. v0.1.0).
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored.
+# One-time setup on PyPI: add a trusted publisher for project `vouch-kb`
+# pointing at vouchdev/vouch, workflow `release.yml`, environment `pypi`.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

vouch_kb-0.1.0/.github/workflows/schema-check.yml

@@ -0,0 +1,62 @@
+name: schema-check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - "src/vouch/models.py"
+      - "schemas/**"
+
+# Regenerate schemas from pydantic models and fail if the result
+# differs from what's committed. This catches the "I edited models.py
+# but forgot to regenerate schemas/" PR.
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: regenerate schemas
+        run: |
+          python3 - <<'PY'
+          import json, sys
+          sys.path.insert(0, 'src')
+          from vouch.models import (
+              Source, Evidence, Claim, Entity, Relation, Page,
+              Session, AuditEvent, Proposal,
+              ContextItem, ContextQuality, ContextPack, Capabilities,
+          )
+          models = {
+              'source': Source, 'evidence': Evidence, 'claim': Claim,
+              'entity': Entity, 'relation': Relation, 'page': Page,
+              'session': Session, 'audit-event': AuditEvent,
+              'proposal': Proposal, 'context-item': ContextItem,
+              'context-quality': ContextQuality, 'context-pack': ContextPack,
+              'capabilities': Capabilities,
+          }
+          for slug, m in models.items():
+              s = m.model_json_schema()
+              s['$schema'] = 'https://json-schema.org/draft/2020-12/schema'
+              s['$id'] = f'https://vouch.dev/schemas/{slug}.schema.json'
+              open(f'schemas/{slug}.schema.json', 'w').write(
+                  json.dumps(s, indent=2, sort_keys=True)
+              )
+          PY
+
+      - name: assert no drift
+        run: |
+          if ! git diff --exit-code schemas/; then
+            echo "::error::schemas/ is out of sync with src/vouch/models.py."
+            echo "Run the regenerate snippet in schemas/README.md and commit."
+            exit 1
+          fi

vouch_kb-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.swp
+.DS_Store

vouch_kb-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-pyyaml]

vouch_kb-0.1.0/.vouch/.gitignore

@@ -0,0 +1,3 @@
+proposed/
+state.db
+state.db-*

vouch_kb-0.1.0/.vouch/audit.log.jsonl

@@ -0,0 +1,9 @@
+{"actor":"a","created_at":"2026-05-20T12:34:59.663398Z","data":{},"dry_run":false,"event":"kb.init","id":"0dfce4809698401cbbc490bf8e71f953","object_ids":[],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T05:51:53.568471Z","data":{},"dry_run":false,"event":"source.add","id":"f38a5315877047b09155df4cef62fdfb","object_ids":["06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c"],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T05:52:06.487422Z","data":{"slug_hint":"vouch-uses-a-review-gated-proposal-workflow-agents-propose-c"},"dry_run":false,"event":"proposal.claim.create","id":"bc066c732d9d45a5a8038aebdf737a02","object_ids":["20260521-055206-7d6d92d6"],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T05:52:34.380239Z","data":{"reason":"Verified by source code inspection"},"dry_run":false,"event":"proposal.claim.approve","id":"119f617462cd4c1d9427148d7986d96c","object_ids":["20260521-055206-7d6d92d6","vouch-uses-a-review-gated-proposal-workflow-agents-propose-c"],"reversible":true}
+{"actor":"vouch-verify","created_at":"2026-05-21T06:04:28.109538Z","data":{"checked":1,"failed":0},"dry_run":false,"event":"source.verify","id":"0f0aaac0a9d741edb7782a4b01b44f8e","object_ids":[],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T06:05:28.018745Z","data":{},"dry_run":false,"event":"kb.init","id":"803be831d1114cdc8466e85fa0b9e9b6","object_ids":[],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T06:05:54.067884Z","data":{},"dry_run":false,"event":"source.add","id":"0b451622d85246089a1d04c45d56c007","object_ids":["67478e72acfb8fac3a059143e95c95f5cc6f7e8d4dccc05fbcea8dbccb8a4eba"],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T06:06:58.649209Z","data":{},"dry_run":false,"event":"source.add","id":"b72feb84d842486490bb7616c616a08c","object_ids":["67478e72acfb8fac3a059143e95c95f5cc6f7e8d4dccc05fbcea8dbccb8a4eba"],"reversible":true}
+{"actor":"a","created_at":"2026-05-21T06:07:08.973490Z","data":{"slug_hint":"vouch-enforces-a-review-gate-on-agent-writes"},"dry_run":false,"event":"proposal.claim.create","id":"9ef38f6a9d8c4e02ad3fd196c49bcc6f","object_ids":["20260521-060708-2b81cdab"],"reversible":true}

vouch_kb-0.1.0/.vouch/claims/vouch-uses-a-review-gated-proposal-workflow-agents-propose-c.yaml

@@ -0,0 +1,22 @@
+id: vouch-uses-a-review-gated-proposal-workflow-agents-propose-c
+text: 'Vouch uses a review-gated proposal workflow: agents propose claims citing evidence
+  sources, and proposals must be explicitly approved (kb_approve) before becoming
+  durable artifacts in the knowledge base. This prevents hallucinated or low-quality
+  knowledge from persisting without human oversight.'
+type: observation
+status: working
+confidence: 0.9
+evidence:
+- 06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c
+entities: []
+supersedes: []
+superseded_by: null
+contradicts: []
+scope: project
+tags:
+- architecture
+- review-gate
+created_at: '2026-05-21T05:52:34.267699Z'
+updated_at: '2026-05-21T05:52:34.267705Z'
+last_confirmed_at: null
+approved_by: a

vouch_kb-0.1.0/.vouch/config.yaml

@@ -0,0 +1,7 @@
+version: 1
+review:
+  require_human_approval: true
+retrieval:
+  backends:
+  - fts5
+  - substring

vouch_kb-0.1.0/.vouch/decided/20260521-055206-7d6d92d6.yaml

@@ -0,0 +1,25 @@
+id: 20260521-055206-7d6d92d6
+kind: claim
+proposed_by: a
+session_id: null
+proposed_at: '2026-05-21T05:52:06.481764Z'
+payload:
+  id: vouch-uses-a-review-gated-proposal-workflow-agents-propose-c
+  text: 'Vouch uses a review-gated proposal workflow: agents propose claims citing
+    evidence sources, and proposals must be explicitly approved (kb_approve) before
+    becoming durable artifacts in the knowledge base. This prevents hallucinated or
+    low-quality knowledge from persisting without human oversight.'
+  type: observation
+  confidence: 0.9
+  evidence:
+  - 06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c
+  entities: []
+  tags:
+  - architecture
+  - review-gate
+rationale: Verified by reading the source code in src/vouch/proposals.py and src/vouch/server.py
+  — the propose/approve separation is a core architectural decision.
+status: approved
+decided_at: '2026-05-21T05:52:34.378311Z'
+decided_by: a
+decision_reason: Verified by source code inspection

vouch_kb-0.1.0/.vouch/sources/06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c/content

@@ -0,0 +1,6 @@
+This conversation explored the vouch project source code to understand how the MCP server works.
+Key findings: vouch exposes 40 MCP tools via FastMCP stdio transport, organized into read tools,
+write/proposal tools (review-gated), lifecycle management, session management, and maintenance tools.
+Sources are de-duplicated by SHA256 content hash. Claims require at least one evidence citation and
+go through a proposal → approve/reject workflow before becoming durable artifacts. All mutations are
+audit-logged to .vouch/audit.log.jsonl.

vouch_kb-0.1.0/.vouch/sources/06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c/meta.yaml

@@ -0,0 +1,12 @@
+id: 06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c
+type: transcript
+locator: /tmp/vouch-conversation-source.txt
+title: Claude Code conversation — vouch exploration
+hash: 06d8519f8dcf4149d23c8a48984541b2e9365ec364e7e58192e28ed149a2c47c
+immutable: true
+scope: project
+byte_size: 539
+media_type: text/plain
+created_at: '2026-05-21T05:51:53.562157Z'
+metadata: {}
+tags: []