Change Proof

Turn a local git diff into a clean change, verification, and risk proof packet.

Status

• Stage: published
• Priority: 1
• GitHub remote: https://github.com/ccmqcy/change-proof
• Package registry: https://www.npmjs.com/package/change-proof
• Current implementation: local TypeScript CLI

Why This Exists

AI coding often produces a patch faster than a reviewer can understand it. The missing artifact is not another diff view; it is a short proof packet that says what changed, why it matters, what was actually verified, what was not verified, and what risk remains.

Differentiation

• Not a generic diff viewer.
• Not an AI reviewer that claims correctness.
• Focused on evidence wording: verified, not verified, risk, and next check.

MVP

Command:

npx change-proof report --test "npm test"

Inputs:

• git diff --stat
• git diff --name-only
• optional test command output

Outputs:

• change-proof-report.md
• optional change-proof-report.json

Install From Source

npm install
npm run build
node dist/cli.js report --help

After npm publication:

npx change-proof@latest report --help

Install from npm:

npm install -g change-proof
change-proof --version

Usage

Generate a Markdown report for the current Git repository:

node dist/cli.js report

Generate Markdown and JSON, and include a verification command:

node dist/cli.js report --test "npm test" --json change-proof-report.json

Inspect another repository:

node dist/cli.js report -C ../my-repo --base origin/main --output reports/change-proof.md

Fail the CLI when the verification command fails:

node dist/cli.js report --test "npm test" --fail-on-test-failure

Windows --test Quoting

Keep the --test value simple on Windows shells:

node dist/cli.js report --test "npm test"
node dist/cli.js report --test "node --version"

Avoid deeply nested quotes such as node -e "console.log('ok')", because PowerShell and cmd.exe can pass those quotes differently. For complex checks, put the check in an npm script and call that script:

{
  "scripts": {
    "verify": "npm test && npm run build"
  }
}

node dist/cli.js report --test "npm run verify"

Output Shape

The Markdown report includes:

• summary counts
• files grouped as source, test, docs, config, generated, asset, or other
• path-based risk signals
• actual verification command output when --test is provided
• explicit Not Verified notes
• raw git diff --stat

Example console output:

Change Proof: files=1 risks=1 high=1 verification=PASS
Wrote report=change-proof-report.md json=change-proof-report.json

First Features

• Group changed files by type: source, test, docs, config, generated.
• Detect risky paths: auth, payment, migration, config, workflow, dependency.
• Run one optional verification command.
• Never mark anything verified unless a command actually ran.

Commands

npm run build
npm test
npm run verify
npm run publish:dry
node dist/cli.js report --help

npm Publish Readiness

Current package version: 0.1.2

The project is published to npm:

npm view change-proof version --registry https://registry.npmjs.org/
npx --registry https://registry.npmjs.org/ --yes change-proof@latest --version

Both commands have been verified to return 0.1.2.

Prepared checks:

• npm run npm:preflight
• npm run pack:dry
• npm run verify:install
• npm run verify
• npm run publish:dry

Important: this machine's default npm registry points to https://registry.npmmirror.com, so publish scripts explicitly use https://registry.npmjs.org/.

Future manual publishes run a strict auth check first:

npm run publish:manual

If publishing with a granular access token that has bypass 2FA enabled, set this explicitly for that shell:

$env:CHANGE_PROOF_NPM_BYPASS_2FA="1"
npm run publish:manual

The first npm publish is documented in docs/npm-publish-preflight-2026-06-01.md.

Current Verification

See docs/verification-2026-06-01.md.

Similar Tools And Risk

Duplicate risk: medium.

Adjacent tools exist around diff viewing, AI review, and PR summarization. The project should stay narrow: local diff to verification receipt.

Routes

Route	Purpose
README.md	Project entry
docs/	Research, design notes, verification evidence
src/	CLI source
tests/	Node test runner tests
scripts/	npm preflight, package install verification, and publish support scripts
.github/workflows/ci.yml	GitHub CI

Release Notes

Before GitHub release, complete ../../docs/operations/github-publish-checklist.md.