Technical Reference

Requirements

Node.js 22 or newer. No runtime dependencies. Works on Windows, macOS and Linux (see test report for what was actually run).

Install

npx intentsutra-ai doctor
npm install -g intentsutra-ai        # installs `intentsutra` and `intentsutra-ai`

Commands

CommandPurpose
initcreate .intentsutra/ in the workspace
ingest --file Fimport .md, .txt or .json (object, array, or {requirements: []}; max 500 items)
list / review --idlist requirements; show questions and draft acceptance
revise --id --file --revision Nnew revision when canonical content changed
approve --id --revision N --reviewer --note --confirm-humanself-attested approval
link --id --revision N --kind K --ref R [--outcome O]evidence link; kinds code test test-run release ticket pr
attest --id --revision N --reviewer --note --confirm-humanhuman attestation of linked evidence
trace / impact --idderived state; stale approvals and links
report [--out DIR]traceability JSON, MD, HTML, feature file, questions, assumptions, manifest
audit [--out DIR] [--quiet] [--strict]independent audit: audit-report.json, .md, .html
verify --report FILEcheck an audit report seal
serve [--token T] [--port P]read-only loopback API (also INTENTSUTRA_TOKEN)
install-ide --target DIR --host H [--force]project-local instruction pack
doctor, --version, helpdiagnostics

Boolean flags (--confirm-human, --force, --quiet, --strict) never consume the next argument.

Outcome values

test-run: passed | failed | unknown. release: released | blocked | unknown.

Provenance labels

LabelMeaning
local-file-hash-observedthe file existed in the workspace and its SHA-256 was recorded
user-imported-test-result-not-independently-verifieda human supplied a pass/fail; nothing ran
user-imported-release-claim-not-independently-verifieda human supplied a release claim
unverified-referenceticket or PR text; a pointer only

Data files

FileContent
.intentsutra/requirements.jsonregistry (schema 1.0): requirements, history, approvals, links, attestations
.intentsutra/audit.jsonlone JSON event per line, each with prevHash and hash (SHA-256 of canonical JSON)
.intentsutra/reports/default report folder

Hash input is canonical JSON (keys sorted recursively), so the same content always hashes the same.

Audit report schema (1.0)

{schemaVersion, tool, generatedAt, projectId, verdict, summary{requirements, checks, passed, failed, bySeverity, attested, auditEvents, auditChainHead}, checks[{id,title,severity,status,failures,note,limitation}], requirements[], limitations[], seal}. seal is the SHA-256 of the canonical report without the seal.

API (loopback, read-only)

GET /health, /trace, /requirements, /report.md, /report.html. Header Authorization: Bearer <token>, token of 24+ characters. Non-loopback peers get 403, non-GET 405, no CORS, Cache-Control: no-store, 120 requests per minute per peer.

Programmatic use

import {init, ingest, approve, link} from 'intentsutra-ai/packages/core/registry.mjs';
import {runAudit} from 'intentsutra-ai/packages/core/assurance.mjs';

The library API is not yet covered by a semver stability promise; the CLI and file formats are.

Error codes

NOT_INITIALIZED, ALREADY_INITIALIZED, NOT_FOUND, APPROVAL_REQUIRED, ATTESTATION_REQUIRED, INSUFFICIENT_EVIDENCE, STALE_REVISION, INVALID_KIND, INVALID_OUTCOME, INVALID_JSON, INVALID_INPUT, UNSUPPORTED_INPUT, PATH_ESCAPE, UNSAFE_FILE, TOO_LARGE, ID_CONFLICT, AUDIT_TAMPER.