ChangeFront Reference Edition

ChangeFront is a working local application that demonstrates how AI tools can help with evidence-based work without being allowed to make final decisions or change documents on their own.

In plain English, you give ChangeFront approved evidence, such as policies, standards, research, or technical records. An AI client can use that evidence to draft a recommendation or propose a document change. A human reviewer must then approve or reject the work. ChangeFront tracks where every claim came from, whether the evidence is still current, and what happened at each step.

ChangeFront is the governance and review layer around an AI workflow. It does not include an AI model, connect to external systems, or automatically apply changes.

The entire demo uses synthetic organizations, domains, controls, records, and outcomes. It is not a production deployment, an employer system, or evidence of organizational adoption.

This project is source-available for noncommercial use. Commercial use requires a separate written license from Robert Ganey. See Licensing.

What the demo includes

• Python 3.12 and SQLite implementation with no runtime package dependencies.
• Registered HTTPS provenance, applicability, verification, confidence, content hashes, and expiry.
• Immutable evidence versions with separate current-version pointers and append-only state history.
• Automatic recommendation and proposal invalidation when supporting evidence is superseded or becomes stale.
• Human-only approval enforced in the shared domain service, including audit records for denied AI attempts.
• Non-applying document proposals: even an approved proposal never writes a target document.
• A responsive loopback reviewer UI and a real JSON API.
• A modern MCP 2026-07-28 stdio server with per-request metadata, server/discover, tools/list, and tools/call.
• Deterministic service, SQLite, HTTP, approval-boundary, and MCP subprocess tests.

Quick start on Windows

From PowerShell:

.\launch-demo.ps1

The script finds Python 3.12 or later, creates an ignored local database under runtime, seeds the synthetic scenario, binds to 127.0.0.1, waits for health, and opens the dashboard. Press Ctrl+C in the terminal to stop it.

If Python is not on PATH:

$env:CHANGEFRONT_PYTHON = 'C:\path\to\python.exe'
.\launch-demo.ps1

Verify

.\verify.ps1

This runs every test three consecutive times and writes verification.json. The report records exact test cases by module, total executions, each pass result, output hashes, the Python version, determinism controls, and a source snapshot hash.

Direct CLI use

$env:PYTHONPATH = "$PWD\src"
python -m changefront_ref --db runtime/changefront.db seed
python -m changefront_ref --db runtime/changefront.db summary
python -m changefront_ref --db runtime/changefront.db audit-verify
python -m changefront_ref --db runtime/changefront.db serve --seed --port 8765

MCP stdio

$env:PYTHONPATH = "$PWD\src"
python -m changefront_ref --db runtime/changefront-mcp.db mcp --seed

The MCP adapter emits only newline-delimited JSON-RPC messages on stdout. It is stateless: every request carries protocol version, client identity, and client capabilities in _meta. The 11-tool catalog supports governed evidence, drafting, review submission, staleness evaluation, summaries, and audit verification. It intentionally exposes no approval, decision, document-apply, shell, or external-network tool.

mcp-server.example.json shows the client configuration shape. Replace ${PROJECT_ROOT} if the client does not expand placeholders.

Architecture at a glance

Human browser -> loopback web/API --+
MCP client    -> stdio MCP ---------+-> governance service -> SQLite
Local CLI     ----------------------+                       -> audit hash chain

Every adapter shares the same policy-enforcing service. A transport cannot bypass provenance, current-evidence, verification, invalidation, or human-review rules.

Repository map

src/changefront_ref/
  storage.py                  SQLite schema and immutability triggers
  service.py                  governance rules and state transitions
  web.py                      loopback UI and JSON API
  mcp.py                      MCP 2026-07-28 modern stdio server
  fixtures/synthetic_demo.json
  static/index.html
tests/
  test_service.py             domain, storage, approval, and audit tests
  test_api.py                 real HTTP server tests
  test_mcp.py                 discovery, metadata, tools, framing, and subprocess tests
docs/
  ARCHITECTURE.md
  TRUST_MODEL.md
  EVIDENCE_POLICY.md
  REVIEWER_GUIDE.md
  EVALUATION.md
scripts/verify.py             repeated verification and machine-readable report

Trust boundary in one sentence

AI clients may ingest evidence and draft or submit work for review, but only an explicitly confirmed human_reviewer can record a decision, and this application never applies a proposal to a target document.

Read Architecture, Trust model, and Reviewer guide before evaluating the implementation.

Standards reference

The stdio adapter follows the current stable Model Context Protocol 2026-07-28 specification, including per-request versioning, required server discovery, the newline-delimited stdio transport, and modern tool result shapes.

License

Source-available under the PolyForm Noncommercial License 1.0.0. Noncommercial use, modification, and distribution are permitted only under those terms. Commercial use requires a separate written license from Robert Ganey. See Licensing.