osovv / grace-cli

<skill>
<installationcontract>Invoke the installed stable grace binary directly. If it is missing, install it with bun add -g @osovv/grace-cli. Do not default to bunx, npx, or the rc dist-tag.</installationcontract>

<commands>

• Active-baseline preflight before observed writes: grace lint --path PROJECT --assertions current
• Selected baseline: grace lint --path PROJECT --change C-ID --assertions baseline (add --run-commands when the baseline declares MustPassCommand)
• Selected target: grace lint --path PROJECT --change C-ID --assertions target --run-commands
• Final execution gate: grace lint --path PROJECT --change C-ID --assertions final --run-commands
• Parallel preflight: grace lint --path PROJECT --parallel-preflight
• Status: grace status --path PROJECT --with modules --json
• Navigation: grace module find|show, grace verification find|show, and grace file show.

</commands>

<commandruncontract>
--run-commands executes each declared MustPassCommand value once per lint, fail-fast, with a default 600s per-command timeout (--command-timeout SECONDS overrides, 0 disables). Plan, progress, and per-command result lines go to stderr; the lint report and JSON go to stdout, so piping stdout stays safe. Agents and pipes get compact output by default; interactive terminals see live streamed command output. Force modes with --verbose (live) or --quiet (compact); they are mutually exclusive, and --format json is always compact. Full combined output of every command is stored per run under ~/.cache/grace/run-commands/<project>/runs/<run>/ (respecting XDG_CACHE_HOME) with a machine-readable meta.json; failing commands print a bounded output tail plus the absolute log path. meta.json records the VCS identity the run executed against (head, branch, dirty, all null outside a git repository) plus the writing pid; it is written at run start with status running and rewritten on completion, and a running record whose process is gone is reclassified as killed on a later run. Pruning keeps the newest passing run of every change indefinitely, so the evidence an archived change cites stays on disk; the retention count applies only to non-passing runs — failed, timed out, interrupted, superseded by a newer pass of the same change, unbound to a change, or missing a readable meta.json. The count defaults to 10, is set project-wide by runLogRetention in .grace-lint.json, and is overridden per run by --keepRuns N. --keepRuns 0 keeps no non-passing runs at all, which deletes the current run as soon as it fails and leaves its printed log path dangling. Interrupted runs (SIGINT/SIGTERM) kill the whole command process group, record interrupted status in meta.json, and exit 130.</commandruncontract>

<lifecyclecommandcontract>current evaluates active approved baselines and is not end-state evidence. Keep MustPassCommand entries as leaf project checks; do not nest grace lint, grace status, or another GRACE lifecycle command inside plan assertions. Run selected target/final lint externally.</lifecyclecommandcontract>

<failure_contract>
Lint, status, and navigation commands validate before returning records. JSON argument/runtime failures are one { "schemaVersion": "1.0.0", "ok": false, "error": { ... } } object on stdout. Text failures are one concise actionable line with a nonzero exit code and no stack trace.
</failure_contract>

<runtime_contract>
TypeScript/JavaScript analysis is bundled. Python and Dart governed files require their runtimes on PATH; missing runtimes fail closed with actionable analysis.runtime-missing diagnostics instead of silently dropping parity checks.
</runtime_contract>

<migrationboundary>GRACE 4 commands do not dual-validate legacy GRACE 3 docs. Use grace-migrate.</migrationboundary>
</skill>