Functional Specification

What GovernSutra 0.2.1 does, per capability. Each row names the command and the proof.

Capabilities

IDCapabilityCommandBehavior
F1Initialize workspaceinitCreates .governsutra/ with registry, policies, evidence index, empty audit chain. Idempotent.
F2Register a systemregister --input FILEValidates the record; rejects duplicate or unsafe IDs, missing owner or purpose, bad enums, invalid control status. Writes an audit event.
F3Import repository manifestsimport-manifests --repo DIRLoads governance/ai-systems/*.json; verifies optional integrity.sha256; registers valid ones as unconfirmed repository declarations; never overwrites an existing ID.
F4Assessassess --id IDEvaluates ten rules, risk indicator, completeness, unknowns; emits JSON, Markdown or HTML. Decision is always HUMAN_REVIEW_REQUIRED.
F5Reportreport --id ID --out DIRWrites assessment.json, .md, .html.
F6Scanscan --repo DIRCandidate discovery with file digest, JSON pointer and line.
F7Diffdiff --a A --b BCompares two system records or two scans; lists changes and re-review triggers.
F8Evidenceevidence add / evidence verifyHash a file by reference (expiry, verifier optional); re-hash later to find drift, missing files, expiry. Exit code 2 on any problem.
F9Audit chainaudit verifyVerifies sequence, previous-hash links and event hashes.
F10Independent-style auditaudit --out DIRRuns 31 checks; writes sealed JSON, MD and HTML. Exit 2 on failure.
F11Seal verifyverify --report FILERecomputes the canonical SHA-256 seal.
F12Install IDE adapterinstall-ide --host H --target DIRCopies host instructions plus agents, skills, rules, workflows, schemas. --dry-run, --force.
F13Local APIserveRead-only, loopback, bearer token.
F14DoctordoctorNode version, hosts, offline status.

The ten rules

RuleQuestionPass requires
GOV-001Named accountabilityowner and risk owner present
GOV-002Intended-use boundariesintended use and at least one prohibited use
GOV-003No compliance claimsengine design rule (always pass; tested by audit)
GOV-004Evidence provenanceverified controls resolve to hashed evidence and a named verifier, none expired
GOV-005Data minimizationdata sources declared, none with raw data attached
GOV-006Human decision authorityeach checkpoint names role and authority
GOV-007Version traceabilityevery model and tool records a version
GOV-008Risk uncertainty visibleall six risk inputs declared
GOV-009Least privilegeevery tool lists permissions
GOV-010Lifecycle reviewactive or in-review system has a future review date

Statuses: pass, fail, unknown, not-applicable, exception-approved. See Evidence model and rules.

Control statuses

planned, implemented, evidence-attached, verified-by-named-reviewer, failed, unknown, not-applicable, exception-approved. Only verified-by-named-reviewer with evidence and a verifier can satisfy GOV-004. File presence is never verification.

Exceptions

Valid only with: named human approver, rationale, scope, target rule, and a future expiry. Agent approvers are invalid. An expired or invalid exception leaves the rule failing and says why.

Non-functional requirements

Offline; Node 22+; zero dependencies; 2 MiB per file; 200 manifests; Windows, macOS and Linux CI; deterministic output except timestamps.

Out of scope

Legal classification, compliance verdicts, certification, runtime monitoring of AI systems, collecting raw personal data or secrets.