Use STIG from Gradle
The ai.exida.stig Gradle plugin is STIG's command interface. There is no separate STIG CLI: task names such as stigCheckModel and stigGenerateHtml are the commands, and the repository's Gradle wrapper supplies execution, dependency resolution, caching, continuous mode, and task help.
Root and element scope
Run from the consumer-project directory that contains settings.gradle.kts.
The leading : makes the scope unambiguous. An unqualified task run from a subdirectory may resolve to that subproject's task instead of the root aggregate.
Model-check context
An element's stigCheckModel discovers all model declarations in its Kotlin module, including nested containers and declarations with incorrect containment. It follows the outgoing model references from that content and loads the complete models of the directly connected modules. Every CREATE viewpoint supplies context, including viewpoints whose checks are disabled. The same loader handles the checked module and its context modules, once each. Context objects supply evidence while the task evaluates the selected module's subjects. References originating only in context modules do not recursively expand the complete-model inventory. Ordinary transitive Kotlin runtime dependencies remain available. Child descriptors declared in a parent's context do not make missing child specifications the parent's module-level responsibility. Child viewpoints or configured element ownership identify the child's module; the full-project check also covers child descriptors without their own module.
Analysis bypass does not change this loading contract. An authored usedIn or propagatesTo link to a grandparent selects the target module as ordinary direct context. Analysis.enabled = false, or an absent parent Analysis, does not itself request any extra module. Rules validate the grandparent target and the permitted single bypass using the loaded relation context; they do not turn context modules into additional rule subjects or discovery roots. Missing links remain missing-link findings. See Bypass one Analysis level.
Incoming coverage is an absence check and requires complete contributor content. A grandchild referenced only by a context module's Design does not get loaded automatically. If the checked module needs that content, supply explicit model context or run the full-project :stigCheckModel; insufficient context remains a loading diagnostic, not a finding that the incoming link is absent.
An element descriptor can be declared in its parent's module while its specifications live in its own module. Gradle's configured element.id supplies the lightweight element-to-module catalog. Source identifiers select conservative compilation candidates before the task graph executes; instantiated references select the actual model context. This preparation reads the checked module's sources, not its parents' Analysis flags, and does not construct a project-wide requirement or failure index. For references computed by arbitrary Kotlin factories, declare any additional compilation context explicitly, without introducing a Kotlin dependency cycle:
stigModelContext prepares complete content for loading; it does not make that module's declarations available to the Kotlin compiler. A source reference to another module's failure declaration still needs an ordinary Kotlin dependency, such as implementation(project(":components:parent")).
IDEA follows the same approach: the inspected file identifies its module, then STIG loads that module and its connected models. Indexed references to viewpoint roots' element arguments locate specification modules whose element descriptors are declared elsewhere. For example, a child requirements file can reference its element while the parent's requirements file contains the allocation to that child. The parent requirements become visible even before any child requirement declares a derivedFrom link. Parent analyses and tests are included in the same way. The shared scope, ownership index, and rule engine live in stig-core; Gradle supplies compiled objects and IDEA supplies objects read from Kotlin PSI.
Automated rules execute in this context, including incoming failure and interface-analysis coverage from Design.children, with one Analysis bypass where applicable. Missing required context fails batch execution; it is not an unassessed rule result. IDEA reports a loading diagnostic for unsupported or incomplete source and continues checks that can run with the available information. Semantic obligations are opt-in review requests, with missing engineering evidence identified in their messages.
stigCheckModel defaults to automatic checks. Select --checks all to include manual review requests or --checks manual to produce only manual review work. Manual modes also write manual-reviews.md next to the canonical reports and print its clickable file URI in the final task summary. The checklist lists selected semantic rules and their outcomes, including reasons when rules are not applicable, followed by review requests grouped by module and rule with subjects, related identities, source locations, and the rule contract. A Requirements.sources link supplies a reference; it does not import requirement text. Requirement-quality rules need actual Requirement objects in the checked module. Loading other modules as context does not select their requirements for review. Record review verdicts, evidence, reviewer, and source revision in an authored review report. STIG does not ingest those verdicts as build approvals; rerunning a checklist does not mean that completed judgments failed.
For automatic findings from every Analysis viewpoint in the project:
The option is plural and accepts repeated selections. A module-scoped task checks that module; it loads children as context where needed but does not select their findings. Use the root task for all modules, or name each selected module task explicitly. A subsequent ordinary stigGenerateHtml regenerates automatic findings after a manual/all run.
The root :stigCheckModel loads the complete project model once, prepares one inventory, and evaluates each module's subjects and connected context using its resolved viewpoint settings and failAt threshold. It writes separate results, preserving each finding's owning project, originating viewpoint, and source location in SARIF as well as JSON:
Check | Output directory |
|---|---|
One module |
|
Complete project |
|
One module within the complete-project result |
|
Each directory contains canonical problems.jsonl, model_check_rules.json, and derived stig-check.sarif. The complete-project check is explicit; ordinary element report generation uses the element's module check. Gradle reuses unchanged compilation outputs. IDEA caches the context and rule results across files of a module and invalidates them when source or module changes can affect content or specification ownership.
Configure once, override when needed
Classification-difference information
By default, model checks report INFO when an entity's ASIL or failure severity exceeds the maximum of all its known contributors. The common classification policy defines the relationships, aggregation and reporting locations.
Disable these advisories project-wide in the root build.gradle.kts:
The value inherits independently through defaults → group → element → module. A more specific modelCheck { reportClassificationDifferences = true } enables them again. The setting applies to module and full project checks, generated reports, and live IDEA inspections. IDEA reads literal Boolean assignments from the Gradle Kotlin DSL, including project defaults, groups["name"] selections, element settings, and module settings. Computed Gradle expressions are resolved by Gradle; live inspection uses the default when it cannot read the setting.
The setting suppresses only these advisories. HIGH violations, required-attribute checks, the allocatedAsil equality contract, and other informational findings remain active. Classification INFO uses SARIF informational and cannot fail a build at any failAt threshold.
Persistent project behavior belongs in Kotlin Gradle DSL:
Task-specific command options are useful for one invocation:
When a task exposes both a Gradle property and an option, the command-line option overrides the configured convention. Do not persist project semantics in shell aliases or environment variables.
Discover the effective contract
The generated Gradle task API is version-matched with this manual and the bundled $stig:project skill. The consumer build is the final authority because a local composite may supply a newer STIG checkout:
Task help is generated by Gradle from the same registered descriptions and @Option declarations used to generate the published API page.
Read the console output
STIG prefixes each event with its area, operation, and kind, such as P6 | analyzer-run | PROGRESS. Ordinary progress, options, artifact paths, and tool completion messages are visible at Gradle's default lifecycle level. --info adds diagnostic detail; --debug adds tracing. These levels control visibility, not success or failure.
Color describes the outcome, using Gradle's terminal palette:
Appearance | Meaning |
|---|---|
Normal text | Routine starts, progress, options, artifacts, successful tool exits, and informational findings |
Green | An explicitly passed validation or a final summary with |
Yellow | A warning or a |
Red | A failed validation, failed summary, failed tool exit, or a |
Green means success, not INFO. A tool exiting successfully does not establish that the enclosing analysis passed. Problem records describe findings and have their own severity and failure threshold; routine progress does not create problem records. Event kinds, results, and severities carry the meaning even with --console=plain or a customized palette.
Messages appear as readable text. Multiline instructions and shell commands retain real line breaks, quotes, and continuation backslashes, so the command block can be copied directly into a terminal. The separate JSONL event stream keeps escaped strings on one line per record for tooling.
STIG displays elapsed times and estimates with explicit units: 0.125 s, 12 s, 2 min 05 s, or 1 h 02 min 03 s. Below ten seconds it retains up to three decimal places; from ten seconds onward it rounds to the nearest whole second. Hours do not wrap at 24. This distinguishes durations from timestamps without requiring a hh:mm:ss legend. JSONL measurements retain their precision. Gradle's own messages and external-tool transcripts use their respective formats.
Published and local-development modes
A normal consumer resolves the version declared by its plugin configuration. If a sibling ../stig checkout is configured as an included build, that source build overrides the published artifact. stigPrintVersion reports the effective plugin; use it instead of guessing from gradle.properties.
The local build also packages the matching Codex plugin before Gradle processes STIG plugin resources. A subsequent explicit stigInstallSkill therefore installs the local task, model, and rule contract.
Ask $stig:project
See Choose a Gradle task for the intent map and Per-element configuration for the persistent DSL.