User Guide

A complete walk-through using the bundled synthetic fixtures. Every command below was run for real; transcripts are in samples/.

1. Check the host

npx intentsutra-ai doctor

2. Create a workspace and import requirements

mkdir demo && cd demo
cp <package>/fixtures/team-invitations.json .
intentsutra init
intentsutra ingest --file team-invitations.json
intentsutra list

You get five requirements (REQ-TEAM-001 to 005). Each shows how many questions are still open.

3. Read the unknowns

intentsutra review --id REQ-TEAM-001

Questions are never answered for you. Candidate scenarios contain [TO CONFIRM] placeholders; they are unapproved drafts.

4. Approve (a human decision)

intentsutra approve --id REQ-TEAM-001 --revision 1 --reviewer "Asha" --note "Reviewed with product owner" --confirm-human

Without --confirm-human, the exact revision, a reviewer and a note, the command is refused. The record says identityVerified: false.

intentsutra link --id REQ-TEAM-001 --revision 1 --kind code --ref src/invite.js
intentsutra link --id REQ-TEAM-001 --revision 1 --kind test-run --ref ci/run-log.txt --outcome passed
intentsutra link --id REQ-TEAM-001 --revision 1 --kind release --ref notes/release.txt --outcome released

Files must live inside the workspace and are hashed. The test-run and release outcomes are what you report; the tool does not run anything.

6. Attest

intentsutra attest --id REQ-TEAM-001 --revision 1 --reviewer "Asha" --note "Evidence reviewed by hand" --confirm-human

Refused unless approval, code, an imported passed test-run and an imported release claim exist for the current revision. The resulting state is human-attested-evidence-linked, never "completed".

7. Change the requirement

intentsutra revise --id REQ-TEAM-001 --file v2.json --revision 1
intentsutra impact --id REQ-TEAM-001

Revision 2 is created. The old approval, links and attestation are kept as history and listed as stale. Linking to revision 1 is now refused (STALE_REVISION).

8. Reports

intentsutra report --out reports          # traceability: JSON, Markdown, HTML, feature file
intentsutra audit  --out audit-out        # independent audit: JSON, Markdown, HTML
intentsutra verify --report audit-out/audit-report.json

Open audit-out/audit-report.html in any browser. It is a single responsive file with light and dark themes and a print style.

9. Reading an audit verdict

VerdictMeaning
PASSno failed checks
PASS-WITH-FINDINGSonly medium or low findings, such as approvals with unanswered questions
FAILa critical or high check failed: broken chain, edited registry, drifted evidence, upgraded label

Use --strict in CI to turn FAIL into exit code 2.

10. Use with an AI coding assistant

intentsutra install-ide --host claude --target ./my-project

Copies instructions into ./my-project/intentsutra/. It never edits global settings and refuses to overwrite without --force.

Troubleshooting

MessageFix
NOT_INITIALIZEDrun intentsutra init in the workspace
STALE_REVISIONread the current revision with list, then retry
PATH_ESCAPEthe file must be inside the workspace
INSUFFICIENT_EVIDENCEadd the missing approval or evidence for the current revision
AUDIT_TAMPERthe audit log was edited; restore it from a backup, do not delete lines