CLI Standard v1.1.0 — diagnostic severity ladder, machine envelope, unified rendering

README.md

@@ -39,7 +39,7 @@ the rules re-attached to every prompt.
 | [`spacecraft-chez-guidelines`](spacecraft-chez-guidelines/) | Functional, safe, concurrent Chez Scheme guidance — R6RS libraries + Akku, pure-first design, `optimize-level` as the safety lever (level 3 = `unsafe`), hand-built mailboxes/channels over real threads (no Fibers), the FFI + AOT/whole-program compilation, and Guile-habit guardrails. |
 | [`spacecraft-clang-guidelines`](spacecraft-clang-guidelines/) | Memory-safe highly-hardened C guidance — NASA Power of 10 Rules (no runtime heap allocation, bounded loops, small functions, high assertion density), MISRA C safety subsets, CERT C secure coding rules, Clang `-fbounds-safety` compiler extensions, and C11 atomics. |
 | [`spacecraft-cli-preference`](spacecraft-cli-preference/) | Modern CLI substitutions: `eza` for `ls`, `rg` for `grep`, `gitway` for Git SSH, etc. Conditional on the local host — substitute only when the tool is installed, fall back to the legacy tool with a note when it isn't, never launch a TUI in the agent's TTY-less shell, and get consent before anything that mutates or deletes. |
-| [`spacecraft-cli-standard`](spacecraft-cli-standard/) | Enforces the Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.0.0) on every CLI. Presence-based agent-env detection (harnesses set descriptive strings, not `=1`), run-to-verify compliance, and no-clobber scaffolding on the user's own machine. |
+| [`spacecraft-cli-standard`](spacecraft-cli-standard/) | Enforces the Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.1.0) on every CLI. Severity-tagged diagnostics (`[ERROR]`/`[WARN]`/`[OK]`/`[INFO]` + machine envelopes), presence-based agent-env detection (harnesses set descriptive strings, not `=1`), run-to-verify compliance, and no-clobber scaffolding on the user's own machine. |
 | [`spacecraft-cli-shell`](spacecraft-cli-shell/) | Syntax-compliance guard for Nushell / Ion / POSIX / Bash commands. Measures the host instead of guessing it, and targets whichever shell will actually execute the command — agent-run, handed to the user, or written to a file. |
 | [`spacecraft-clojure-guidelines`](spacecraft-clojure-guidelines/) | Functional, safe-concurrent Clojure guidance — immutable-first design, reference-type decision tree (atoms / refs+STM / agents / core.async), transducers, lazy-seq discipline, ClojureScript and Babashka platform notes, and `standard-clj` formatting. |
 | [`spacecraft-commonlisp-guidelines`](spacecraft-commonlisp-guidelines/) | Type-safe highly-concurrent Common Lisp guidance (targeting SBCL) — Bordeaux-Threads and `lparallel` pools, compare-and-swap (CAS) atomics, dynamic scope thread-local let-bindings, compile-time type declarations, safe FFI memory hygiene via `cffi:with-foreign-object`, and SBCL compiler optimization flags. |

spacecraft-agentic-cli/SKILL.md

@@ -145,6 +145,14 @@ including:
 Canonical hint strings for every standard error code live in
 `assets/error-hint-catalog.json` — use them as starting points.
 
+**Hint is a field, never a severity.** The severity ladder is exactly
+`error`/`warn`/`ok`/`info` with the `[ERROR]`/`[WARN]`/`[OK]`/`[INFO]`
+tags (`spacecraft-cli-standard` `references/diagnostics.md`); any
+diagnostic of any severity MAY carry a `hint`, and non-error diagnostics
+(the `diagnostic` envelope) benefit from one exactly the same way —
+e.g. the TUI-fallback warning hints the working non-TUI invocation. The
+message states what happened; only the hint says what to run next.
+
 ---
 
 ## §4 — Agent Environment Detection (Behavioral Cascade)
@@ -156,9 +164,9 @@ simultaneously:
 
 | Variable | Output format | Color | TUI | Interactivity | Verbosity |
 |----------|---------------|-------|-----|---------------|-----------|
-| `AI_AGENT` set | json | off | suppressed | non-interactive (--yes implicit) | minimal — failures only |
-| `AGENT` set | json | off | suppressed | non-interactive | minimal |
-| `CI` truthy | json | off | suppressed | non-interactive | normal |
+| `AI_AGENT` set | json | off | suppressed | non-interactive (--yes implicit) | minimal — severity floor `warn` (failures + degradations; no `ok`/`info` chatter) |
+| `AGENT` set | json | off | suppressed | non-interactive | minimal — floor `warn` |
+| `CI` truthy | json | off | suppressed | non-interactive | normal — floor `ok` |
 | `CLAUDECODE` set | (informational) | (per other rules) | (per other rules) | (per other rules) | (per other rules) |
 | `CURSOR_AGENT` set | (informational) | (per other rules) | (per other rules) | (per other rules) | (per other rules) |
 | `GEMINI_CLI` set | (informational) | (per other rules) | (per other rules) | (per other rules) | (per other rules) |
@@ -184,6 +192,10 @@ without inferring agent intent.
 **Read `references/agent-env-detection.md`** for concrete Rust detection
 code, the canonical priority order, and a Bun-style verbosity adaptation
 (suppress passing test logs under `AI_AGENT`; emit only failure traces).
+The verbosity column is defined precisely as the **severity floor** in
+`spacecraft-cli-standard` `references/diagnostics.md` §4: agent mode
+raises the floor to `warn`, `--quiet` to `error`, `--verbose` lowers it
+to `info`; explicit flags beat environment detection.
 
 ---
 

spacecraft-agentic-cli/assets/error-hint-catalog.json

@@ -2,7 +2,7 @@
   "_metadata": {
     "version": "1.0.0",
     "license": "GPL-3.0-or-later",
-    "description": "Canonical hint strings keyed by error.code for Spacecraft Software CLIs. Every hint is a runnable command (paste-test passes). Substitute <tool> with the actual tool name (ferrocast, caliper, etc.).",
+    "description": "Canonical hint strings keyed by error.code for Spacecraft Software CLIs. Every hint is a runnable command (paste-test passes). Substitute <tool> with the actual tool name (ferrocast, caliper, etc.). Warn/info diagnostic codes (spacecraft-cli-standard references/diagnostics.md) follow the same pattern — key by diagnostic.code here rather than maintaining a parallel catalog (e.g. TUI_FALLBACK hints the working non-TUI invocation: <tool> <noun> list --json).",
     "see_also": "references/tips-thinking.md"
   },
 
@@ -48,9 +48,10 @@
   },
 
   "MISSING_DEPENDENCY": {
-    "with_nix": "nix-shell -p <package-name>",
+    "with_nix": "nix run nixpkgs#<package-name> -- <args>",
+    "with_guix": "guix shell <package-name> -- <command>",
     "with_check": "<tool> describe --fields dependencies --json",
-    "context": "Required external tool not in PATH. Per Spacecraft Software standard, prefer Nix package manager. Use --with-check hint when agent should query the dependency list first."
+    "context": "Required external tool not in PATH. Hint the ephemeral run preferred by spacecraft-missing-pkg (nix run / guix shell) — never nix-shell -p (superseded, see tips-thinking.md) and never a durable or system-package-manager install. Use with_check when the agent should query the dependency list first."
   },
 
   "TIMEOUT": {

spacecraft-agentic-cli/references/tips-thinking.md

@@ -336,17 +336,18 @@ test scaffold.
 
 ## §6 — Localization and human-mode rendering
 
-In human (TTY) mode, the hint field SHOULD still be rendered as a
-suggestion to the human user. Format it visibly:
+In human (TTY) mode, the hint field is still rendered as a suggestion to
+the human user, in the unified diagnostic layout defined by
+`spacecraft-cli-standard` `references/diagnostics.md` §5:
 
 ```
-Error: Repository 'foo/bar' does not exist
-  → Try: ferrocast repo list --json
+[ERROR] repository `foo/bar` does not exist
+  hint: ferrocast repo list --json
 ```
 
-The arrow + `Try:` prefix MUST NOT appear in the JSON `hint` field
-itself. It is added at render time only. The JSON hint stays a pure
-runnable string.
+The `[ERROR]` tag and the indented `hint:` label MUST NOT appear in the
+JSON `hint` field itself. They are added at render time only. The JSON
+hint stays a pure runnable string.
 
 **Localization:** the `message` field MAY be localized for human users.
 The `hint` field MUST NOT be localized — it is always the literal command

spacecraft-cli-standard/SKILL.md

@@ -1,30 +1,33 @@
 ---
 name: spacecraft-cli-standard
 description: >
-  Enforces the Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.0.0)
+  Enforces the Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.1.0)
   on every CLI the AI writes or reviews. ALWAYS consult when working on ANY
   command-line interface — new binaries, sub-commands, clap wiring, --json or
-  --format output, exit codes, structured errors to stderr, ratatui TUI,
-  schema introspection, MCP server surface, or CLI tests. Triggers include
-  noun-verb command design, TTY detection, NO_COLOR/FORCE_COLOR, JSON output
-  envelopes, ISO 8601 UTC timestamps, UTF-8 encoding, POSIX compatibility,
-  Nushell/PowerShell 7+/Ion/Bash output, and agent env vars (AI_AGENT, AGENT,
-  CI, CLAUDECODE, CURSOR_AGENT, GEMINI_CLI). If a Spacecraft Software project
-  (Ferrocast, Caliper, Craton, Ironway, Zamak, Bravais, Mawaqit, Flux, or any
-  future project) has a CLI component, this skill governs it — even when the
-  user does not explicitly mention the Standard. Use proactively the moment
-  CLI code appears on the horizon.
+  --format output, exit codes, error/warning/info diagnostics with severity
+  tags, structured errors to stderr, ratatui TUI, schema introspection, MCP
+  server surface, or CLI tests. Triggers include noun-verb command design,
+  TTY detection, NO_COLOR/FORCE_COLOR, JSON output envelopes, ISO 8601 UTC
+  timestamps, UTF-8 encoding, POSIX compatibility, Nushell/PowerShell
+  7+/Ion/Bash output, and agent env vars (AI_AGENT, AGENT, CI, CLAUDECODE,
+  CURSOR_AGENT, GEMINI_CLI). If a Spacecraft Software project (Ferrocast,
+  Caliper, Craton, Ironway, Zamak, Bravais, Mawaqit, Flux, or any future
+  project) has a CLI component, this skill governs it — even when the user
+  does not explicitly mention the Standard. Use proactively the moment CLI
+  code appears on the horizon.
 license: GPL-3.0-or-later
 maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
 website: https://Construct.SpacecraftSoftware.org/
 ---
 
 # Spacecraft Software CLI Standard — Dual-Mode Self-Documenting CLI Framework
 
-**Version:** 1.0.0 | **Spec Date:** 2026-04-10 | **Author:** Mohamed Hammad
+**Version:** 1.1.0 | **Spec Date:** 2026-08-10 | **Author:** Mohamed Hammad
 **Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
 **Copyright:** (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
-**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/) | **Source Spec:** Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.0.0)
+**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/) | **Source Spec:** Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.1.0)
+
+**Changelog:** see [`references/CHANGELOG.md`](references/CHANGELOG.md) for the full version history.
 
 This skill encodes the Spacecraft Software CLI Standard so every CLI the AI writes for a
 Spacecraft Software project ships with two co-equal output personalities: a
@@ -55,7 +58,7 @@ Violation of any item below blocks shipping. No exceptions.
 | 5 | **GPL-3.0-or-later + SPDX header** | Every source file. |
 | 6 | **`--json` on every data-returning command** | With a stable schema. Breaking schema changes require a major version bump + deprecation cycle. JSON output is a superset of text output. |
 | 7 | **stdout = data only, stderr = everything else** | No progress indicators, banners, log lines, or ANSI escapes mixed into stdout. Ever. |
-| 8 | **Structured errors on stderr in machine mode** | JSON object with `error.{code, exit_code, message, hint, timestamp, command, docs_url}`. See `references/exit-codes-errors.md`. |
+| 8 | **Severity-tagged diagnostics on stderr** | Errors: JSON object with `error.{code, exit_code, message, hint, timestamp, command, docs_url}` in machine mode (`references/exit-codes-errors.md`). Warnings/info/success confirmations: the `diagnostic` envelope and the `[ERROR]`/`[WARN]`/`[OK]`/`[INFO]` tag ladder — color is never the sole carrier of meaning (Steelbore Standard §18.2.1). See `references/diagnostics.md`. |
 
 ---
 
@@ -68,7 +71,7 @@ one-liners are the mental anchor, not the spec.
 2. **Exit codes are the agent's control flow** — use the canonical map (§4). Non-zero exit + JSON error object to stderr. [`references/exit-codes-errors.md`]
 3. **Make commands idempotent** — same invocation twice, same result. Prefer `ensure` / `apply` / `sync` over `create` / `delete`. Every destructive command supports `--dry-run`. [`references/validation-safety.md`]
 4. **Self-documenting beats external docs** — every tool ships `<tool> schema` and `<tool> describe` sub-commands, plus `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, `CONTRIBUTING.md` at repo root. [`references/schema-introspection.md`]
-5. **Structured errors, not narrative messages** — JSON error object on stderr in machine mode. The `hint` field carries the exact command to fix the error ("tips thinking"). [`references/exit-codes-errors.md`]
+5. **Structured errors, not narrative messages** — JSON error object on stderr in machine mode. The `hint` field carries the exact command to fix the error ("tips thinking"). Non-error messages use the same discipline: four severities (`error`/`warn`/`ok`/`info`) carrying the §18.2.1 text tags, with `hint` as a field on any diagnostic — never a severity of its own. [`references/exit-codes-errors.md`, `references/diagnostics.md`]
 6. **Design for composability** — stdout is pure data payload. `--fields` limits payload for token budgets. `jsonl` for streaming. [`references/output-modes.md`]
 7. **Consistent noun-verb structure** — `<tool> <noun-singular> <verb>`. Standard verbs: `list`, `get`, `create`, `update`, `delete`, `apply`, `sync`, `describe`, `schema`. Global flags identical across all Spacecraft Software CLIs. [`references/schema-introspection.md`]
 8. **Understand when MCP beats CLI** — tools with >10 sub-commands SHOULD also expose an MCP server via `<tool> mcp`. Lazy-load schemas to avoid context bloat. [`references/mcp-surface.md`]
@@ -86,8 +89,8 @@ behavior. Divergent implementation is a BLOCKER.
 | `--format <fmt>` | One of: `json`, `jsonl`, `yaml`, `csv`, `explore`. |
 | `--fields <f1,f2,...>` | Restrict output to listed fields. Reduces token cost. |
 | `--dry-run` | Emit action plan as JSON; no side effects. MUST be accepted by every write / delete / destructive command. |
-| `--verbose` / `-v` | Diagnostic output to stderr. |
-| `--quiet` / `-q` | Suppress non-error stderr. |
+| `--verbose` / `-v` | Lower the severity floor to `info`: emit everything, including diagnostic narration and raw subprocess passthrough. See `references/diagnostics.md` §4. |
+| `--quiet` / `-q` | Raise the severity floor to `error`: errors only on stderr. Mutually exclusive with `--verbose` (exit 2 if combined). |
 | `--no-color` | Disable ANSI color. Equivalent to `--color=never`. |
 | `--color <when>` | `never` / `always` / `auto`. |
 | `--help` / `-h` | Help text with ≥2 examples per sub-command (one demonstrating `--json`). Footer MUST include project URL (e.g., `https://<ProjectName>.SpacecraftSoftware.org/`) and maintainer name. |
@@ -184,6 +187,7 @@ Read before implementing; don't fly blind.
 |------|---------------------------|
 | `references/output-modes.md` | Human mode rendering, machine mode output, color precedence, Spacecraft Software palette tokens, JSON envelope, metadata wrapper |
 | `references/exit-codes-errors.md` | Any error path, structured error schema, "tips thinking" hint pattern, `error.code` enum values |
+| `references/diagnostics.md` | Any non-payload message — severity ladder (`[ERROR]`/`[WARN]`/`[OK]`/`[INFO]`), message style rules, the `diagnostic` machine envelope, the `--quiet`/`--verbose`/agent severity floor, human-mode tag rendering and colors |
 | `references/schema-introspection.md` | `<tool> schema` (JSON Schema Draft 2020-12), `<tool> describe` manifest, `CLAUDE.md` / `AGENTS.md` / `SKILL.md` / `CONTRIBUTING.md` context files, noun-verb structure |
 | `references/shell-compat.md` | Output that must parse in POSIX sh, Bash 5+, Brush, Nushell 0.111+, PowerShell 7.6+, or Ion (RedoxOS) |
 | `references/tui-explore.md` | `--format explore` / `-E` TUI mode, ratatui+crossterm, dual CUA+Vim keybindings, alt-screen buffer, search/filter/sort/detail/export |
@@ -266,5 +270,5 @@ host; route to them rather than restating their rules.
 
 ---
 
-*End of SKILL.md. Full normative spec: Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.0.0) "Dual-Mode
-Self-Documenting CLI Framework", 2026-04-10.*
+*End of SKILL.md. Full normative spec: Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.1.0) "Dual-Mode
+Self-Documenting CLI Framework", 2026-08-10.*