User guide

Before you start#

Install Node.js 20 or newer. Check with node --version. You do not need an API key, an account, or npm install inside this repository.

From a clone of this repository the command is:

node packages/cli/bin/pramanasutra.mjs doctorCopy

From anywhere, once the repository is public on GitHub:

npx pramanasutra doctorCopy

npx downloads the repository. The CLI that then runs still does not call a model and does not scan until you ask it to.

Check a project#

node packages/cli/bin/pramanasutra.mjs release-check --path path/to/projectCopy

You get a paragraph on the terminal and four files in ./pramanasutra-reports/:

scan and release-check use the same exit codes: 2 for NO_GO, 3 for REVIEW_REQUIRED, 0 for READY_FOR_HUMAN_APPROVAL. A scan with no evidence file exits 3.

--changed adds names from git diff when the directory is a Git checkout. Those names are not a test selection. If git cannot read the directory, the report says git diff was not available for this directory, so no changed-file list was collected.

Choose another folder with --out reports/feature-a. Skip the files with --no-report if you only want the exit code.

The terminal line always includes Tests executed by this tool: NO. If you did not pass --evidence, the gate cannot be ready.

Read the result#

Open report.html first if you are a person. The first block is the decision:

• NO_GO (exit 2). Something blocking was seen, usually a focused test, or the evidence file says the tests failed. Do not release on this output.
• REVIEW_REQUIRED (exit 3). The static picture is not blocking, but evidence is missing, untrusted, empty, or the scan was partial, or tests, CI or a license are missing under the policy. A person has to look.
• READY_FOR_HUMAN_APPROVAL (exit 0). The policy's checks passed. It is still not permission to deploy.

Then read "Supplied test evidence". If it says no file was supplied, the pass/fail counts you might imagine are not in this report. Then read the findings table: severity, rule, file:line, and the fix. The limitations at the bottom are part of the result, not a footnote to skip.

Samples you can open without scanning anything:

This repository's own audit: audit/report.md and audit/report.html.

Supply evidence#

The CLI will not run your tests. You run them, then describe the result. Minimum shape:

{
  "schemaVersion": "1.0.0",
  "source": "local-executed",
  "command": "npm test",
  "executedAt": "2026-11-06T12:00:00Z",
  "exitCode": 0,
  "passed": 37,
  "failed": 0,
  "skipped": 1
}Copy

source is local-executed when you ran it on a machine you control, or ci-ingested when the counts came from the CI log. Use external-unverified when you cannot stand behind the file; the gate will stay in review.

node packages/cli/bin/pramanasutra.mjs release-check --path . --evidence evidence.jsonCopy

Check a file alone:

node packages/cli/bin/pramanasutra.mjs verify --evidence evidence.jsonCopy

In this repository, node scripts/ci-gate.mjs runs the unit tests and builds that file from the summary. It does not hand-type the counts. Copy that pattern in your own CI rather than committing a stale evidence file.

Choose a policy#

node packages/cli/bin/pramanasutra.mjs release-check --path . --evidence evidence.json --policy policies/strict.jsonCopy

Strict mode turns skipped tests into NO_GO. Recommended mode reports them and does not block on them. Write your own file with only the keys in the technical reference. A typo in a key is an error, on purpose.

Install the skills#

node packages/cli/bin/pramanasutra.mjs init --ide claude --target /path/to/your/appCopy

The target must already exist. The command copies folders. It does not call the model. If you already have a pramanasutra-prime skill there, it stops. Read the existing file before you pass --force.

Then tell the assistant, in your own words or this one:

PramanaSutra Prime: assess this repository's test quality and release readiness. Stay read-only, cite file and line, separate observed facts from executed results, and ask before running any tests.

The skill is supposed to refuse to invent a pass. If a host ignores the skill, that is a host limitation. It is listed as not verified in Roadmap and status.

Exclude paths#

Put .pramanasutraignore at the root of the project you scan. Example:

# generated fixtures, not the product
fixtures/
examples/sample-app/Copy

The report will say how many paths were excluded. If you exclude your real tests, the gate can look healthier than the project is. That is your file. Read the limitation line.

Fix a NO_GO for a focused test#

1. Open the path in the finding, for example tests/a.test.js:2.
2. Remove .only, fit or fdescribe.
3. Run the project's real test command and keep the output.
4. Run release-check again with --evidence pointing at a file that matches that output.

Removing .only without running the suite only clears the static finding. Without evidence the gate becomes REVIEW_REQUIRED, which is still not ready. That is the correct outcome.

When something fails#

More terms: FAQ.