IF Commons GitHub

GRC headless verbs

0007Active

0007-grc-surface · owner if · domain grc

The verbs

FR-001checkpassing

grcBranch(host) MUST give a branch grc of exactly the commands check, assess, explain, evidence and bundle verify (0011-grc-bundles), each declared as an action of Headless with its kind, effect and reach, and the model MUST have no defect by Headless' modelProblems with the reach required.

Enforced (check): .github: cd commons/grc && bun run verify — suite/surface.test.ts

Proved by: grc/suite/surface.test.ts

Written in: grc/src/surfaces/headless/mod.ts

Tests: passed: suite/surface.test.ts the branch has exactly check, assess, explain, evidence and bundle verify, and the model h

FR-002checkpassing

grc check [id...] MUST run the checks (all, or those named) over the subjects of the host, be a read-only report, and return the results as the data of the outcome, a problem for each result that is not pass, accepted or not-applicable (a fail as an error, a pending or warn as a warning), and the exit status of Headless' governance for those problems.

Enforced (check): .github: cd commons/grc && bun run verify — suite/surface.test.ts

Proved by: grc/suite/surface.test.ts

Written in: grc/src/surfaces/headless/mod.ts

Tests: passed: suite/surface.test.ts check runs the checks, returns the results as data and a problem for each that is not pass

FR-003checkpassing

grc assess [--format <id>] [--out <file>] MUST assemble the assessment from the results and exceptions, apply the exceptions, and write it through the serializer the format names in the registry of serializers (the document itself where none is named); an unknown format MUST be a usage problem that names the registered ids; writing a file MUST make it an action that --dry-run previews.

Enforced (check): .github: cd commons/grc && bun run verify — suite/surface.test.ts

Proved by: grc/suite/surface.test.ts

Written in: grc/src/surfaces/headless/mod.ts

Tests: passed: suite/surface.test.ts assess writes the assessment in the format a registered serializer names, refuses an unkno

FR-004checkpassing

grc explain <id> MUST say, for an id of a control URN, policy, check or requirement (or a problem code of bundle verify, with what happened, the likely cause and the fix), what it is, what it maps to and what shows it, and for a result id why it has its status; an unknown id MUST be a problem that names the nearest ids.

Enforced (check): .github: cd commons/grc && bun run verify — suite/surface.test.ts

Proved by: grc/suite/surface.test.ts

Written in: grc/src/surfaces/headless/mod.ts

Tests: passed: suite/surface.test.ts explain says what a control, policy, check or requirement is and what it maps to, and an u

FR-005checkpassing

grc evidence [list|verify] MUST list the evidence of the store the host gives with its digests and ages and by verify read each object back and report every digest that does not match, a read-only report whose mismatches are errors.

Enforced (check): .github: cd commons/grc && bun run verify — suite/surface.test.ts

Proved by: grc/suite/surface.test.ts

Written in: grc/src/surfaces/headless/mod.ts

Tests: passed: suite/surface.test.ts evidence lists the store with digests and verify reports each object that does not have it

FR-006checkpassing

Every verb MUST give the same data under --json as the typed outcome holds, and MUST write nothing but what it was asked to write.

Enforced (check): .github: cd commons/grc && bun run verify — suite/surface.test.ts

Proved by: grc/suite/surface.test.ts

Written in: grc/src/surfaces/headless/mod.ts

Tests: passed: suite/surface.test.ts every verb gives the data of its typed outcome and writes nothing but what it was asked to

Scenarios

  • Given a host with one failing check, When grc check --json runs, Then the data holds the result, the exit status is that of an error problem, and nothing is written, per FR-002.
  • Given grc assess --format nothing, When the verb runs, Then a usage problem names the formats registered, per FR-003.

Out of scope

  • A tool-server or REST surface (Headless gives those beside the command line); the editing of governance documents.

Edge cases

  • No checks loaded: check reports an empty run and a hint, not a failure, per FR-002.

Assumptions

  • The host is made by the program that uses the library, which registers the runners it wants.

Open questions

OQ-1open question

Whether grc check should offer --on to run on Headless' targets.

Key entities

  • Host, Branch.

Success criteria

SC-001success criterion

A program of three lines that registers a runner gives a working grc check.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

GRC, surfaces/headless/mod

Titles, headings, exports, tables, columns and requirements. Esc closes.