sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/specs/opsx-onboard-skill/spec.md

@@ -1,167 +0,0 @@
-# opsx-onboard-skill Specification
-
-## Purpose
-Define `/opsx:onboard` behavior for guiding users through an end-to-end OpenSpec workflow on their real codebase.
-
-## Requirements
-### Requirement: OPSX Onboard Skill
-
-The system SHALL provide an `/opsx:onboard` skill that guides users through their first complete OpenSpec workflow cycle with narration and real codebase work.
-
-#### Scenario: Skill invocation
-
-- **WHEN** user invokes `/opsx:onboard`
-- **THEN** agent checks if OpenSpec is initialized
-- **AND** if not initialized, prompts user to run `openspec init` first
-- **AND** if initialized, proceeds with onboarding flow
-
-#### Scenario: Welcome and expectations
-
-- **WHEN** onboarding begins
-- **THEN** agent displays welcome message explaining what will happen
-- **AND** sets expectation of ~15 minute duration
-- **AND** explains the workflow phases: explore → new → artifacts → apply → archive
-
-### Requirement: Codebase Analysis for Task Suggestions
-
-The skill SHALL analyze the user's codebase to suggest appropriately-scoped starter tasks.
-
-#### Scenario: Codebase scanning
-
-- **WHEN** onboarding reaches task selection phase
-- **THEN** agent scans codebase for small improvement opportunities
-- **AND** looks for: TODO/FIXME comments, missing error handling, functions without tests, outdated dependencies, type: any in TypeScript, console.log in production code, missing input validation
-- **AND** checks recent git commits for context on current work
-
-#### Scenario: Task suggestion presentation
-
-- **WHEN** agent has analyzed codebase
-- **THEN** agent presents 3-4 specific task suggestions with scope estimates
-- **AND** each suggestion includes: task description, estimated scope (files/lines), why it's a good starter
-- **AND** offers option for user to specify their own task
-
-#### Scenario: Scope guardrail
-
-- **WHEN** user selects or describes a task that is too large
-- **THEN** agent gently redirects toward smaller scope
-- **AND** suggests breaking down or deferring the large task
-- **AND** offers appropriately-sized alternatives
-
-### Requirement: Explore Phase Demo
-
-The skill SHALL briefly demonstrate explore mode before creating a change.
-
-#### Scenario: Brief explore demonstration
-
-- **WHEN** task is selected
-- **THEN** agent briefly demonstrates `/opsx:explore` by investigating relevant code
-- **AND** explains explore mode is for thinking before doing
-- **AND** keeps this phase short (not a full exploration session)
-- **AND** transitions to change creation
-
-### Requirement: Guided Artifact Creation
-
-The skill SHALL guide users through each artifact with narration explaining the purpose.
-
-#### Scenario: Change creation with narration
-
-- **WHEN** creating the change directory
-- **THEN** agent runs `openspec new change "<name>"` with derived kebab-case name
-- **AND** explains what a "change" is (container for thinking and planning)
-- **AND** shows the folder structure that was created
-- **AND** pauses for user acknowledgment before proceeding
-
-#### Scenario: Proposal creation with narration
-
-- **WHEN** creating proposal.md
-- **THEN** agent explains proposals capture WHY we're making this change
-- **AND** drafts proposal based on selected task
-- **AND** shows draft to user for approval before saving
-- **AND** explains the sections (Why, What Changes, Capabilities, Impact)
-
-#### Scenario: Specs creation with narration
-
-- **WHEN** creating spec files
-- **THEN** agent explains specs define WHAT we're building in detail
-- **AND** explains the requirement/scenario format
-- **AND** creates spec file(s) based on proposal capabilities
-- **AND** notes that specs become documentation that stays in sync
-
-#### Scenario: Design creation with narration
-
-- **WHEN** creating design.md
-- **THEN** agent explains design captures HOW we'll build it
-- **AND** notes this is where technical decisions and tradeoffs live
-- **AND** for small changes, acknowledges design may be brief
-- **AND** creates design based on proposal and specs
-
-#### Scenario: Tasks creation with narration
-
-- **WHEN** creating tasks.md
-- **THEN** agent explains tasks break work into checkboxes
-- **AND** explains these drive the apply phase
-- **AND** generates task list from design and specs
-- **AND** shows tasks and asks if ready to implement
-
-### Requirement: Guided Implementation
-
-The skill SHALL implement tasks with narration connecting back to artifacts.
-
-#### Scenario: Implementation with narration
-
-- **WHEN** implementing tasks
-- **THEN** agent announces each task before working on it
-- **AND** implements the change in the codebase
-- **AND** occasionally references how specs/design informed decisions
-- **AND** marks each task complete as it finishes
-- **AND** keeps narration light (not over-explaining)
-
-#### Scenario: Implementation completion
-
-- **WHEN** all tasks are complete
-- **THEN** agent announces completion
-- **AND** summarizes what was done
-- **AND** transitions to archive phase
-
-### Requirement: Archive with Explanation
-
-The skill SHALL archive the completed change and explain what happened.
-
-#### Scenario: Archive with narration
-
-- **WHEN** archiving the change
-- **THEN** agent explains archive moves change to dated folder
-- **AND** runs archive process
-- **AND** shows where archived change lives
-- **AND** explains the long-term value (finding decisions later)
-
-### Requirement: Recap and Next Steps
-
-The skill SHALL conclude with a recap and command reference.
-
-#### Scenario: Final recap
-
-- **WHEN** onboarding is complete
-- **THEN** agent summarizes the workflow phases completed
-- **AND** emphasizes this rhythm works for any size change
-- **AND** provides command reference table (/opsx:explore, /opsx:new, /opsx:ff, /opsx:continue, /opsx:apply, /opsx:verify, /opsx:archive)
-- **AND** suggests next actions (try /opsx:new or /opsx:ff on something)
-
-### Requirement: Graceful Exit Handling
-
-The skill SHALL handle users who want to stop mid-way.
-
-#### Scenario: User wants to stop
-
-- **WHEN** user indicates they want to stop during onboarding
-- **THEN** agent acknowledges gracefully
-- **AND** notes that the in-progress change is saved
-- **AND** explains how to continue later with `/opsx:continue <name>`
-- **AND** exits without pressure
-
-#### Scenario: User wants quick reference only
-
-- **WHEN** user says they just want to see the commands
-- **THEN** agent provides command cheat sheet
-- **AND** exits gracefully with encouragement to try `/opsx:new`
-

package/OpenSpec-main/openspec/specs/opsx-verify-skill/spec.md

@@ -1,189 +0,0 @@
-# opsx-verify-skill Specification
-
-## Purpose
-Define `/opsx:verify` behavior for assessing implementation completeness, correctness, and coherence against change artifacts.
-
-## Requirements
-### Requirement: Verify Skill Invocation
-The system SHALL provide an `/opsx:verify` skill that validates implementation against change artifacts.
-
-#### Scenario: Verify with change name provided
-- **WHEN** agent executes `/opsx:verify <change-name>`
-- **THEN** the agent verifies implementation for that specific change
-- **AND** produces a verification report
-
-#### Scenario: Verify without change name
-- **WHEN** agent executes `/opsx:verify` without a change name
-- **THEN** the agent prompts user to select from available changes
-- **AND** shows only changes that have implementation tasks
-
-#### Scenario: Change has no tasks
-- **WHEN** selected change has no tasks.md or tasks are empty
-- **THEN** the agent reports "No tasks to verify"
-- **AND** suggests running `/opsx:continue` to create tasks
-
-### Requirement: Completeness Verification
-The agent SHALL verify that all required work has been completed.
-
-#### Scenario: Task completion check
-- **WHEN** verifying completeness
-- **THEN** the agent reads tasks.md
-- **AND** counts tasks marked `- [x]` (complete) vs `- [ ]` (incomplete)
-- **AND** reports completion status with specific incomplete tasks listed
-
-#### Scenario: Spec coverage check
-- **WHEN** verifying completeness
-- **AND** delta specs exist in `openspec/changes/<name>/specs/`
-- **THEN** the agent extracts all requirements from delta specs
-- **AND** searches codebase for implementation of each requirement
-- **AND** reports which requirements appear to have implementation vs which are missing
-
-#### Scenario: All tasks complete
-- **WHEN** all tasks are marked complete
-- **THEN** report "Tasks: N/N complete"
-- **AND** mark completeness dimension as passed
-
-#### Scenario: Incomplete tasks found
-- **WHEN** some tasks are incomplete
-- **THEN** report "Tasks: X/N complete"
-- **AND** list each incomplete task
-- **AND** mark as CRITICAL issue
-- **AND** suggest: "Complete remaining tasks or mark as done if already implemented"
-
-### Requirement: Correctness Verification
-The agent SHALL verify that implementation matches the specifications.
-
-#### Scenario: Requirement implementation mapping
-- **WHEN** verifying correctness
-- **THEN** for each requirement in delta specs:
-  - Search codebase for implementation
-  - Identify relevant files and line numbers
-  - Assess whether implementation satisfies the requirement
-
-#### Scenario: Scenario coverage check
-- **WHEN** verifying correctness
-- **THEN** for each scenario in delta specs:
-  - Check if the scenario's conditions are handled in code
-  - Check if tests exist that cover the scenario
-  - Report coverage status
-
-#### Scenario: Implementation matches spec
-- **WHEN** implementation appears to satisfy a requirement
-- **THEN** report which files/lines implement it
-- **AND** mark requirement as covered
-
-#### Scenario: Implementation diverges from spec
-- **WHEN** implementation exists but doesn't match spec intent
-- **THEN** report the divergence as WARNING
-- **AND** explain what differs
-- **AND** suggest: either update implementation or update spec to match reality
-
-#### Scenario: Missing implementation
-- **WHEN** no implementation found for a requirement
-- **THEN** report as CRITICAL issue
-- **AND** suggest: "Implement requirement X" with guidance on what's needed
-
-### Requirement: Coherence Verification
-The agent SHALL verify that implementation is sensible and follows design decisions.
-
-#### Scenario: Design.md adherence check
-- **WHEN** verifying coherence
-- **AND** design.md exists for the change
-- **THEN** extract key decisions from design.md
-- **AND** verify implementation follows those decisions
-- **AND** report any deviations
-
-#### Scenario: No design.md
-- **WHEN** verifying coherence
-- **AND** no design.md exists
-- **THEN** skip design adherence check
-- **AND** note "No design.md to verify against"
-
-#### Scenario: Design decision followed
-- **WHEN** implementation follows a design decision
-- **THEN** report as confirmed
-- **AND** cite evidence from code
-
-#### Scenario: Design decision violated
-- **WHEN** implementation contradicts a design decision
-- **THEN** report as WARNING
-- **AND** explain the contradiction
-- **AND** suggest: either update implementation or update design.md
-
-#### Scenario: Code pattern consistency
-- **WHEN** verifying coherence
-- **THEN** check if new code follows existing project patterns
-- **AND** flag any significant deviations as suggestions
-
-### Requirement: Verification Report Format
-The agent SHALL produce a structured, prioritized report.
-
-#### Scenario: Report summary
-- **WHEN** verification completes
-- **THEN** display summary scorecard:
-  ```text
-  ## Verification Report: <change-name>
-
-  ### Summary
-  | Dimension    | Status   |
-  |--------------|----------|
-  | Completeness | X/Y      |
-  | Correctness  | X/Y      |
-  | Coherence    | Followed |
-  ```
-
-#### Scenario: Issue prioritization
-- **WHEN** issues are found
-- **THEN** group and display in priority order:
-  1. CRITICAL - Must fix before archive (missing implementation, incomplete tasks)
-  2. WARNING - Should fix (divergence from spec/design, missing tests)
-  3. SUGGESTION - Nice to fix (pattern inconsistencies, minor improvements)
-
-#### Scenario: Actionable recommendations
-- **WHEN** reporting an issue
-- **THEN** include specific, actionable fix recommendation
-- **AND** reference relevant files and line numbers where applicable
-- **AND** avoid vague suggestions like "consider reviewing"
-
-#### Scenario: All checks pass
-- **WHEN** no issues found across all dimensions
-- **THEN** display:
-  ```text
-  All checks passed. Ready for archive.
-  ```
-
-#### Scenario: Critical issues found
-- **WHEN** CRITICAL issues exist
-- **THEN** display:
-  ```text
-  X critical issue(s) found. Fix before archiving.
-  ```
-- **AND** do NOT suggest running archive
-
-#### Scenario: Only warnings/suggestions
-- **WHEN** no CRITICAL issues but warnings exist
-- **THEN** display:
-  ```text
-  No critical issues. Y warning(s) to consider.
-  Ready for archive (with noted improvements).
-  ```
-
-### Requirement: Flexible Artifact Handling
-The agent SHALL gracefully handle changes with varying artifact completeness.
-
-#### Scenario: Minimal change (tasks only)
-- **WHEN** change has only tasks.md
-- **THEN** verify task completion only
-- **AND** skip spec and design checks
-- **AND** note which checks were skipped
-
-#### Scenario: Change with specs but no design
-- **WHEN** change has tasks.md and delta specs but no design.md
-- **THEN** verify completeness and correctness
-- **AND** skip design adherence
-- **AND** still check code coherence against project patterns
-
-#### Scenario: Full change (all artifacts)
-- **WHEN** change has proposal, design, specs, and tasks
-- **THEN** perform all verification checks
-- **AND** cross-reference artifacts for consistency

package/OpenSpec-main/openspec/specs/rules-injection/spec.md

@@ -1,102 +0,0 @@
-# rules-injection Specification
-
-## Purpose
-Define how per-artifact rules from project config are injected into generated instructions with deterministic formatting and validation.
-
-## Requirements
-### Requirement: Inject rules only for matching artifact
-
-The system SHALL inject rules from config into instructions only when the artifact ID matches a key in the rules object.
-
-#### Scenario: Rules exist for the artifact
-- **WHEN** loading instructions for "proposal" and config has `rules: { proposal: ["Rule 1", "Rule 2"] }`
-- **THEN** instruction output includes rules section with both rules
-
-#### Scenario: No rules for the artifact
-- **WHEN** loading instructions for "design" and config has `rules: { proposal: [...] }`
-- **THEN** instruction output does not include `<rules>` tags
-
-#### Scenario: Rules object is undefined
-- **WHEN** config omits the rules field or rules is undefined
-- **THEN** instruction output does not include `<rules>` tags for any artifact
-
-#### Scenario: Rules array is empty for artifact
-- **WHEN** config has `rules: { proposal: [] }`
-- **THEN** instruction output does not include `<rules>` tags
-
-### Requirement: Format rules with XML-style tags and bullet list
-
-The system SHALL wrap rules in `<rules>` tags with each rule as a bulleted list item.
-
-#### Scenario: Single rule for artifact
-- **WHEN** config has `rules: { proposal: ["Include rollback plan"] }`
-- **THEN** instruction output includes `<rules>\n- Include rollback plan\n</rules>\n\n`
-
-#### Scenario: Multiple rules for artifact
-- **WHEN** config has `rules: { proposal: ["Rule 1", "Rule 2", "Rule 3"] }`
-- **THEN** instruction output includes each rule as separate bullet point
-
-#### Scenario: Rules appear after context and before template
-- **WHEN** instructions are generated with both context and rules
-- **THEN** order is `<context>` then `<rules>` then `<template>`
-
-### Requirement: Preserve rule text exactly as provided
-
-The system SHALL inject rule text without modification, escaping, or interpretation.
-
-#### Scenario: Rule contains markdown
-- **WHEN** rule includes markdown like "Use **Given/When/Then** format"
-- **THEN** markdown is preserved in the injected content
-
-#### Scenario: Rule contains special characters
-- **WHEN** rule includes characters like `<`, `>`, quotes
-- **THEN** characters are preserved exactly as written
-
-#### Scenario: Rule is multi-line string
-- **WHEN** rule text contains line breaks
-- **THEN** line breaks are preserved within the bullet point
-
-### Requirement: Support multiple artifacts with different rules
-
-The system SHALL allow different rule sets for different artifacts in the same config.
-
-#### Scenario: Multiple artifacts have rules
-- **WHEN** config has `rules: { proposal: ["P1"], specs: ["S1", "S2"], tasks: ["T1"] }`
-- **THEN** proposal instructions show only ["P1"], specs show only ["S1", "S2"], tasks show only ["T1"]
-
-#### Scenario: Some artifacts have rules, others do not
-- **WHEN** config has rules for proposal and specs only
-- **THEN** design and tasks instructions have no `<rules>` section
-
-### Requirement: Rules are additive to schema guidance
-
-The system SHALL add config rules to the schema's built-in artifact instruction, not replace it.
-
-#### Scenario: Artifact has schema instruction and config rules
-- **WHEN** artifact has built-in instruction from schema and config provides rules
-- **THEN** final instruction contains both schema guidance and config rules
-
-#### Scenario: Rules provide additional constraints
-- **WHEN** schema says "create proposal" and config rules say "include rollback plan"
-- **THEN** agent sees both the schema template and the additional rule
-
-### Requirement: Validate artifact IDs during instruction loading
-
-The system SHALL validate artifact IDs in rules against the schema when instructions are loaded and emit warnings for unknown IDs.
-
-#### Scenario: All artifact IDs are valid
-- **WHEN** instructions loaded and config has `rules: { proposal: [...], specs: [...] }` for schema with those artifacts
-- **THEN** no validation warnings are emitted
-
-#### Scenario: Unknown artifact ID in rules
-- **WHEN** instructions loaded and config has `rules: { unknownartifact: [...] }`
-- **THEN** warning emitted: "Unknown artifact ID in rules: 'unknownartifact'. Valid IDs for schema 'spec-driven': design, proposal, specs, tasks"
-
-#### Scenario: Multiple unknown artifact IDs
-- **WHEN** instructions loaded and config has multiple unknown artifact IDs
-- **THEN** separate warning emitted for each unknown artifact ID
-
-#### Scenario: Validation warnings shown once per session
-- **WHEN** instructions loaded multiple times in same CLI session
-- **THEN** each unique validation warning is shown only once (cached)
-

package/OpenSpec-main/openspec/specs/schema-fork-command/spec.md

@@ -1,71 +0,0 @@
-# schema-fork-command Specification
-
-## Purpose
-Define `openspec schema fork` behavior for cloning existing schemas into project-local schemas with safe overwrite controls.
-
-## Requirements
-### Requirement: Schema fork copies existing schema
-The CLI SHALL provide an `openspec schema fork <source> [name]` command that copies an existing schema to the project's `openspec/schemas/` directory.
-
-#### Scenario: Fork with explicit name
-- **WHEN** user runs `openspec schema fork spec-driven my-custom`
-- **THEN** system locates `spec-driven` schema using resolution order (project → user → package)
-- **AND** copies all files to `openspec/schemas/my-custom/`
-- **AND** updates `name` field in `schema.yaml` to `my-custom`
-- **AND** displays success message with source and destination paths
-
-#### Scenario: Fork with default name
-- **WHEN** user runs `openspec schema fork spec-driven` without specifying a name
-- **THEN** system copies to `openspec/schemas/spec-driven-custom/`
-- **AND** updates `name` field in `schema.yaml` to `spec-driven-custom`
-
-#### Scenario: Source schema not found
-- **WHEN** user runs `openspec schema fork nonexistent`
-- **THEN** system displays error that schema was not found
-- **AND** lists available schemas
-- **AND** exits with non-zero code
-
-### Requirement: Schema fork prevents accidental overwrites
-The CLI SHALL require confirmation or `--force` flag when the destination schema already exists.
-
-#### Scenario: Destination exists without force
-- **WHEN** user runs `openspec schema fork spec-driven my-custom` and `openspec/schemas/my-custom/` exists
-- **THEN** system displays error that destination already exists
-- **AND** suggests using `--force` to overwrite
-- **AND** exits with non-zero code
-
-#### Scenario: Destination exists with force flag
-- **WHEN** user runs `openspec schema fork spec-driven my-custom --force` and destination exists
-- **THEN** system removes existing destination directory
-- **AND** copies source schema to destination
-- **AND** displays success message
-
-#### Scenario: Interactive confirmation for overwrite
-- **WHEN** user runs `openspec schema fork spec-driven my-custom` in interactive mode and destination exists
-- **THEN** system prompts for confirmation to overwrite
-- **AND** proceeds based on user response
-
-### Requirement: Schema fork preserves all schema files
-The CLI SHALL copy the complete schema directory including templates, configuration, and any additional files.
-
-#### Scenario: Copy includes template files
-- **WHEN** user forks a schema with template files (e.g., `proposal.md`, `design.md`)
-- **THEN** all template files are copied to the destination
-- **AND** template file contents are unchanged
-
-#### Scenario: Copy includes nested directories
-- **WHEN** user forks a schema with nested directories (e.g., `templates/specs/`)
-- **THEN** nested directory structure is preserved
-- **AND** all nested files are copied
-
-### Requirement: Schema fork outputs JSON format
-The CLI SHALL support `--json` flag for machine-readable output.
-
-#### Scenario: JSON output on success
-- **WHEN** user runs `openspec schema fork spec-driven my-custom --json`
-- **THEN** system outputs JSON with `forked: true`, `source`, `destination`, and `sourcePath` fields
-
-#### Scenario: JSON output shows source location
-- **WHEN** user runs `openspec schema fork spec-driven --json`
-- **THEN** JSON output includes `sourceLocation` field indicating "project", "user", or "package"
-

package/OpenSpec-main/openspec/specs/schema-init-command/spec.md

@@ -1,76 +0,0 @@
-# schema-init-command Specification
-
-## Purpose
-Define `openspec schema init` behavior for creating project-local schema skeletons in interactive and non-interactive modes.
-
-## Requirements
-### Requirement: Schema init command creates project-local schema
-The CLI SHALL provide an `openspec schema init <name>` command that creates a new schema directory under `openspec/schemas/<name>/` with a valid `schema.yaml` file and default template files.
-
-#### Scenario: Create schema with valid name
-- **WHEN** user runs `openspec schema init my-workflow`
-- **THEN** system creates directory `openspec/schemas/my-workflow/`
-- **AND** creates `schema.yaml` with name, version, description, and artifacts array
-- **AND** creates template files referenced by artifacts
-- **AND** displays success message with created path
-
-#### Scenario: Reject invalid schema name
-- **WHEN** user runs `openspec schema init "My Workflow"` (contains space)
-- **THEN** system displays error about invalid schema name
-- **AND** suggests using kebab-case format
-- **AND** exits with non-zero code
-
-#### Scenario: Schema name already exists
-- **WHEN** user runs `openspec schema init existing-schema` and `openspec/schemas/existing-schema/` already exists
-- **THEN** system displays error that schema already exists
-- **AND** suggests using `--force` to overwrite or `schema fork` to copy
-- **AND** exits with non-zero code
-
-### Requirement: Schema init supports interactive mode
-The CLI SHALL prompt for schema configuration when run in an interactive terminal without explicit flags.
-
-#### Scenario: Interactive prompts for description
-- **WHEN** user runs `openspec schema init my-workflow` in an interactive terminal
-- **THEN** system prompts for schema description
-- **AND** uses provided description in generated `schema.yaml`
-
-#### Scenario: Interactive prompts for artifact selection
-- **WHEN** user runs `openspec schema init my-workflow` in an interactive terminal
-- **THEN** system displays multi-select prompt with common artifacts (proposal, specs, design, tasks)
-- **AND** each option includes a brief description
-- **AND** uses selected artifacts in generated `schema.yaml`
-
-#### Scenario: Non-interactive mode with flags
-- **WHEN** user runs `openspec schema init my-workflow --description "My workflow" --artifacts proposal,tasks`
-- **THEN** system creates schema without prompting
-- **AND** uses flag values for configuration
-
-### Requirement: Schema init supports setting project default
-The CLI SHALL offer to set the newly created schema as the project default.
-
-#### Scenario: Set as default interactively
-- **WHEN** user runs `openspec schema init my-workflow` in interactive mode
-- **AND** user confirms setting as default
-- **THEN** system updates `openspec/config.yaml` with `defaultSchema: my-workflow`
-
-#### Scenario: Set as default via flag
-- **WHEN** user runs `openspec schema init my-workflow --default`
-- **THEN** system creates schema and updates `openspec/config.yaml` with `defaultSchema: my-workflow`
-
-#### Scenario: Skip setting default
-- **WHEN** user runs `openspec schema init my-workflow --no-default`
-- **THEN** system creates schema without modifying `openspec/config.yaml`
-
-### Requirement: Schema init outputs JSON format
-The CLI SHALL support `--json` flag for machine-readable output.
-
-#### Scenario: JSON output on success
-- **WHEN** user runs `openspec schema init my-workflow --json --description "Test" --artifacts proposal`
-- **THEN** system outputs JSON with `created: true`, `path`, and `schema` fields
-- **AND** does not display interactive prompts or spinners
-
-#### Scenario: JSON output on error
-- **WHEN** user runs `openspec schema init "invalid name" --json`
-- **THEN** system outputs JSON with `error` field describing the issue
-- **AND** exits with non-zero code
-