projtruth
projtruth lets an MCP client track requirements, evidence-backed status, file scope, and decisions for a project.
Report the project truth table: every requirement’s computed status and evidence, optionally narrowed to changes since a git ref.
List registered requirements with criterion counts, declared status, and file scope.
Add requirements with ids, titles, acceptance criteria, and file globs that determine staleness.
Declare only
pendingorimplemented;verified,stale, andunverifiedare rejected because they are computed from evidence.Restrict a requirement’s staleness to specific file globs.
Re-scan and index evidence files by criterion id from
.claude/skills/verify-*/evidence/**and.projtruth/evidence/**.Append decisions with reasons to an append-only decision log.
Read the decision log before revisiting settled choices.
Note: it does not run tests or create evidence itself; it reports recorded evidence and freshness.
Uses a Git work tree's commit history and uncommitted file modification times to determine whether requirement-covered code has changed since evidence was recorded, enabling Git-aware freshness and stale/verified status calculation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@projtruth show me which requirements are stale and need re-verification"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
projtruth
Requirements in. Evidence out. No claim without proof.
projtruth is a small MCP server (plus a CLI with the same core) that keeps a
project's promises - requirements, acceptance criteria, the evidence behind
each one, and the decisions that shaped them - and computes which promises are
still true.
It answers three questions, for humans and for agents:
Which requirements are verified, which went stale, which have no evidence?
What exactly backs R3, and when was it written?
Why is it built this way? (append-only decision log)
$ projtruth report
| requirement | status | criteria | evidence | tier | scope | freshest evidence |
|---|---|---|---|---|---|---|
| R1 待办创建(API) | **verified** | 1 | 1 | measured | 1 pattern(s) | 2026-11-13 05:50 |
| R2 待办列表(API) | **verified** | 1 | 1 | measured | 1 pattern(s) | 2026-11-13 05:50 |
| R3 待办完成切换(API) | **stale** | 1 | 1 | measured | 1 pattern(s) | 2026-11-13 05:50 |
| R4 前端界面 | **verified** | 1 | 1 | measured | 2 pattern(s) | 2026-11-13 06:54 |
## Needs attention (1 of 4)
- R3 (stale, re-verify): code changed 12m ago, after evidence 2026-11-13 05:50The status is computed, not declared. A requirement is verified only when
evidence exists and the code it covers has not changed since. There is no
word that grants it: req_set_status accepts only pending and
implemented. A verified left in an older or hand-edited registry with no
evidence behind it reports as unverified.
Install
Zero dependencies, Python 3.8+.
pip install git+https://github.com/Libres-coder/projtruth(Not on PyPI yet - install from the repository, or run python -m projtruth
from a checkout.)
As an MCP server (Claude Code, Cursor, any MCP client):
claude mcp add projtruth -- python -m projtruth.mcp_server
# or point a client at: python /path/to/projtruth/projtruth/mcp_server.pyThe server reads the repo from PROJTRUTH_REPO, else the process cwd - start it
in the project root, or set the variable in the MCP server config.
As a skill (adds the workflow guidance to Claude Code):
git clone https://github.com/Libres-coder/projtruth ~/.claude/skills/projtruthRelated MCP server: reqtrace-mcp
Quickstart
cd your-project
projtruth init # .projtruth/ (commit this)
projtruth import-spec spec.md # reads "### R1 title" + "- 验收: ..." / "- Accept: ..."
projtruth req-scope R1 server.py # optional but recommended - see below
projtruth report # what is actually doneNo spec file? Register requirements directly:
projtruth req-add R5 "Rate limit login" "6th attempt within a minute returns 429" \
--files "app/auth/*.py"Evidence
Evidence is a file whose basename starts with the criterion or requirement id:
.claude/skills/verify-<app>/evidence/<date>/R3.1-post-todos.md # verify-first writes here
.projtruth/evidence/R3.1-post-todos.md # agent-neutral drop boxThe body should contain the real output and a tier word - measured,
inferred or guessed. See references/evidence-format.md.
Evidence quality
A fresh file proves that something ran; the tier says how well. When a
verified requirement's newest evidence is guessed or carries no tier,
report adds an Evidence quality section: the status stays verified
(a fresh file is still fresh), but "fresh" and "proven" stop being the same
word. report --json carries the same fact as evidence_tier, so a consumer
can gate on quality without parsing the table.
A file can also say what it proves, which is how one CI log covers three requirements without being renamed:
projtruth: R1, R2.3An HTML comment (<!-- projtruth: R1 -->) works too, and an explicit
declaration overrides the filename.
Status model
status | meaning |
| evidence exists and is newer than the code it covers |
| evidence exists, code changed after it - re-verify |
| declared done, nothing backs it |
| declared done, no evidence yet |
| not started |
Only pending and implemented can be declared; verified, stale and
unverified are computed from evidence.
Details: references/status-model.md.
Freshness without the mtime lies
git clone and git checkout rewrite every file's timestamp. A mtime-based
tool therefore reports "everything changed just now" on a fresh checkout - the
opposite of the truth. When the repo is a git work tree, projtruth uses the
newest commit that touched the requirement's files, and counts an uncommitted
edit at that file's own mtime - not "now", so a re-run right after an edit
still counts as fresh. Non-git repos fall back to mtime.
.projtruth/, .claude/, .git/, .idea/, graphify-out/, PROGRESS.md,
README*, CHANGELOG*, CONTRIBUTING*, LICENSE* and *.lock never count as
source changes - projtruth init alone must not turn a green repo red. A file
with uncommitted changes counts at its own mtime, not "now", so a fresh re-run
of a check is still newer than the edit it answers.
Scope: precision beats a repo-wide red
Without a scope, any source change marks a requirement stale. Give each one the files it depends on and the report matches what a developer would say:
projtruth req-scope R1 server.py "web/api/**/*.js"Editing server.py then flips R1 to stale and leaves the UI requirement
verified.
A scope that resolves to nothing means "never stale" - a typo fails silently,
and a wrong-case path works on Windows but not in CI. projtruth scopes prints
how every pattern resolves; --strict exits 1 when one cannot match on every
platform:
projtruth scopes
R1 Login is rate-limited
app/auth/*.py glob 3 file(s)
server.py file 1 file(s)MCP tools
tool | for |
| the truth table - call first when asked what is done; pass |
| requirements, criteria count, declared status, scope |
| register a requirement with criteria and file scope |
| declare |
| restrict staleness to file globs |
| re-index evidence by criterion id |
| append-only decision log |
Stdio JSON-RPC 2.0, newline-delimited, no dependencies, UTF-8 forced on Windows.
CI gate
projtruth report --strict # exit 1 unless everything is verified
projtruth report --changed origin/main --strict # PR gate: only what the branch touches--changed lists exactly the requirements the branch's files touch, with the
matched changed files per requirement; a PR that touches no tracked requirement
passes. See references/ci-gate.md for a GitHub Actions
job (use fetch-depth: 0, and note what the gate does not prove).
Commit guard
projtruth hook install # writes .git/hooks/pre-commit
projtruth hook status
projtruth hook uninstallThe guard refuses a commit that stages a change to a requirement which is
verified right now without also staging evidence for it - that commit would
silently turn proof into stale. Already-stale requirements never block, so it
cannot trap a repository that is catching up. PROJTRUTH_ALLOW_STALE=1 and
git commit --no-verify are the explicit escapes; the hook refuses to overwrite
a pre-commit hook it did not write.
Design
One file of state, meant to be committed.
.projtruth/requirements.json(promises) and.projtruth/decisions.jsonl(reasons). No database, no daemon.Computed over declared. Words cannot make a requirement verified.
Small surface. Eight MCP tools; every one answerable from the files.
Agent-neutral. Anything that can write a file can leave evidence; anything that speaks MCP can read the truth.
Related work
verify-first - the pipeline that produces the evidence this tool reads.
skill-audit - audits the skills a Claude Code install has accumulated.
Limitations
import-specis a heuristic over headings and bullet prefixes - check its output.Evidence links by filename prefix;
R3-x.mdfeeds everyR3.ncriterion.A scope glob that matches nothing means "never stale" - a typo fails silently (
projtruth scopes --strictis the check for it).Scope paths follow the repository's spelling: Windows resolves a wrong-case path locally, so a registry written there can match nothing on Linux/CI. Write the path as
git ls-filesprints it.Inside a git submodule, edits are invisible to the superproject's history.
Unscoped requirements go stale on any source change (by design).
Only registered requirements are tracked; undocumented work is invisible.
It does not run anything. It reports what was recorded, and when.
The commit guard only exists where
projtruth hook installwas run.
License
MIT
Available Tools
8 toolsdecideA
Append a decision with its reason to the project's decision log. Use when a non-obvious choice is made (library, data model, trade-off) so a later session does not re-litigate it.
Inputs: decision (required), why.
decisions_listA
Read the project decision log (newest last) before re-opening a settled question.
Inputs: no named parameters.
evidence_scanA
Re-read the evidence folders and index them by criterion id. Sources: .claude/skills/verify-*/evidence/** and .projtruth/evidence/**.
Inputs: no named parameters.
req_addA
Register a requirement with acceptance criteria. Use when the user states a feature or a promise the project should keep. Criteria are auto-numbered R.; they are what evidence files link to.
Inputs: id (required), title (required), files, criteria.
req_listB
List registered requirements, their criteria count, declared status and file scope.
Inputs: no named parameters.
req_scopeA
Restrict a requirement's staleness to specific file globs. Without scope, any source change in the repo marks it stale; with scope, only changes to matching files do.
Inputs: id (required), files (required).
req_set_statusA
Declare a requirement's status: pending or implemented. verified, stale and unverified are computed from evidence and are rejected here - write an evidence file instead.
Inputs: id (required), status (required).
status_reportA
Where the project actually stands: every requirement with its computed status (verified/stale/unverified/pending) and the evidence behind it. Call this first when asked what is done, what is left, or whether a feature is really finished. Pass changed_since to narrow it to what a branch or PR touches.
Inputs: changed_since.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct resource+action pair: decisions (decide vs decisions_list), requirements (req_add, req_scope, req_set_status, req_list), evidence (evidence_scan), and reporting (status_report). The only mild overlap is req_list vs status_report, but descriptions clarify that one shows declared registration data while the other shows computed status plus evidence. No tool appears to duplicate another.
Most tools follow a noun-prefixed grouping convention (req_add, req_scope, req_set_status, req_list, decisions_list, evidence_scan, status_report), which makes the families readable, but the bare verb `decide` breaks the pattern and `req_set_status` mixes noun+verb+noun while `decisions_list` and `status_report` are noun+noun. The set is still understandable but not a single predictable verb_noun scheme.
Eight tools is well within a healthy range and each addresses a distinct part of the requirement/decision/evidence lifecycle. Nothing feels padded or redundant; every tool has a clear role in the workflow.
The core lifecycle is covered (capture requirements, scope, set status, read; log and read decisions; scan evidence; report status), but there is no way to update or delete a requirement, remove or amend a decision, or edit criteria after creation. Writing evidence files is implied to happen outside the tool surface, which is a deliberate but notable gap for agent workflows.
Maintenance
Related MCP Connectors
Requirements authority for AI coding agents: binding requirements and acceptance criteria.
QA platform for agents: coverage signals, in-repo test plans, verified tests and release governance.
Versioned artifact review for people and AI agents, with contextual comments and human control.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnforces protocol-driven development by validating requirements, designs, scope, and acceptance evidence, while maintaining immutable, traceable governance archives.-
- AlicenseAqualityBmaintenanceEnables tracing every code change to a requirement and every requirement to a test that actually exercises it, with gap analysis, coverage, change-impact mapping, and evidence reports for Python and C/C++. Enforces human-only sign-off and an independent reviewer that cannot edit code, so AI-written changes can be audited and reproduced.12Apache 2.0
- AlicenseAqualityBmaintenanceRequirements knowledge base for coding agents, stored per Git branch in your repo, with Prolog checks for contradictions, untraced code and unproven requirements.1612AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceGives AI agents structured tools to maintain a living requirements traceability graph — requirements to user stories, cucumber scenarios, screens and phase results — so coverage and its trend across releases can be queried on demand and explored through a web dashboard.33 npmMIT