Skip to main content
Glama

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:50

The 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.py

The 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/projtruth

Related 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 done

No 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 box

The 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.3

An HTML comment (<!-- projtruth: R1 -->) works too, and an explicit declaration overrides the filename.

Status model

status

meaning

verified

evidence exists and is newer than the code it covers

stale

evidence exists, code changed after it - re-verify

unverified

declared done, nothing backs it

implemented

declared done, no evidence yet

pending

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

status_report

the truth table - call first when asked what is done; pass changed_since to scope it to a branch

req_list

requirements, criteria count, declared status, scope

req_add

register a requirement with criteria and file scope

req_set_status

declare pending / implemented (verified, stale, unverified are refused)

req_scope

restrict staleness to file globs

evidence_scan

re-index evidence by criterion id

decide / decisions_list

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 uninstall

The 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.

  • verify-first - the pipeline that produces the evidence this tool reads.

  • skill-audit - audits the skills a Claude Code install has accumulated.

Limitations

  • import-spec is a heuristic over headings and bullet prefixes - check its output.

  • Evidence links by filename prefix; R3-x.md feeds every R3.n criterion.

  • A scope glob that matches nothing means "never stale" - a typo fails silently (projtruth scopes --strict is 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-files prints 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 install was run.

License

MIT

Available Tools

8 tools
decideA

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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enforces protocol-driven development by validating requirements, designs, scope, and acceptance evidence, while maintaining immutable, traceable governance archives.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      12
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Requirements knowledge base for coding agents, stored per Git branch in your repo, with Prolog checks for contradictions, untraced code and unproven requirements.
      16
      12
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives 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 npm
      MIT