# stella explain - Block Explanation Commands

**Sprint:** SPRINT_20260117_026_CLI_why_blocked_command

## Overview

The `stella explain` command group provides commands for understanding why artifacts are blocked by policy gates. This addresses the M2 moat requirement: **"Explainability with proof, not narrative."**

When an artifact is blocked, `stella explain` produces a **deterministic trace** with **referenced evidence artifacts**, enabling:
- Clear understanding of which gate blocked the artifact
- Actionable suggestions for remediation
- Verifiable evidence chain
- Deterministic replay for verification

---

## Commands

### stella explain block

Explain why an artifact was blocked by policy gates.

**Usage:**
```bash
stella explain block <digest> [options]
```

**Arguments:**
- `<digest>` - Artifact digest in any of these formats:
  - `sha256:abc123...` - Full digest with algorithm prefix
  - `abc123...` - Raw 64-character hex digest (assumed sha256)
  - `registry.example.com/image@sha256:abc123...` - OCI reference (digest extracted)

**Options:**

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--format <format>` | `-f` | Output format: `table`, `json`, `markdown` | `table` |
| `--show-evidence` | `-e` | Include full evidence artifact details | false |
| `--show-trace` | `-t` | Include policy evaluation trace | false |
| `--replay-token` | `-r` | Include replay token in output | false |
| `--output <path>` | `-o` | Write to file instead of stdout | stdout |
| `--offline` | | Query local verdict cache only | false |

---

## Output Formats

### Table Format (Default)

Human-readable format optimized for terminal display:

```
Artifact: sha256:abc123def456789012345678901234567890123456789012345678901234
Status: BLOCKED

Gate: VexTrust
Reason: Trust score below threshold (0.45 < 0.70)
Suggestion: Obtain VEX statement from trusted issuer or add issuer to trust registry

Evidence:
  [VEX   ] vex:sha256:de...23  vendor-x      2026-01-15T10:00:00Z
  [REACH ] reach:sha256...56   static        2026-01-15T09:55:00Z

Replay: stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000
```

### JSON Format

Machine-readable format for CI/CD integration:

```json
{
  "artifact": "sha256:abc123def456789012345678901234567890123456789012345678901234",
  "status": "BLOCKED",
  "gate": "VexTrust",
  "reason": "Trust score below threshold (0.45 < 0.70)",
  "suggestion": "Obtain VEX statement from trusted issuer or add issuer to trust registry",
  "evaluationTime": "2026-01-15T10:30:00+00:00",
  "policyVersion": "v2.3.0",
  "evidence": [
    {
      "type": "VEX",
      "id": "vex:sha256:def456789abc123",
      "source": "vendor-x",
      "timestamp": "2026-01-15T10:00:00+00:00",
      "retrieveCommand": "stella evidence get vex:sha256:def456789abc123"
    },
    {
      "type": "REACH",
      "id": "reach:sha256:789abc123def456",
      "source": "static-analysis",
      "timestamp": "2026-01-15T09:55:00+00:00",
      "retrieveCommand": "stella evidence get reach:sha256:789abc123def456"
    }
  ],
  "replayCommand": "stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000"
}
```

### Markdown Format

Suitable for embedding in GitHub issues, PR comments, or documentation:

```markdown
## Block Explanation

**Artifact:** `sha256:abc123def456789012345678901234567890123456789012345678901234`
**Status:** BLOCKED

### Gate Decision

| Property | Value |
|----------|-------|
| Gate | VexTrust |
| Reason | Trust score below threshold (0.45 < 0.70) |
| Suggestion | Obtain VEX statement from trusted issuer or add issuer to trust registry |
| Policy Version | v2.3.0 |

### Evidence

| Type | ID | Source | Timestamp |
|------|-----|--------|-----------|
| VEX | `vex:sha256:de...23` | vendor-x | 2026-01-15 10:00 |
| REACH | `reach:sha256...56` | static-analysis | 2026-01-15 09:55 |

### Verification

```bash
stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000
```
```

---

## Examples

### Basic Block Explanation

```bash
# Get basic explanation of why an artifact is blocked
stella explain block sha256:abc123def456789012345678901234567890123456789012345678901234
```

### JSON Output for CI/CD

```bash
# Get JSON output for parsing in CI/CD pipeline
stella explain block sha256:abc123... --format json --output block-reason.json

# Parse in CI/CD
GATE=$(jq -r '.gate' block-reason.json)
REASON=$(jq -r '.reason' block-reason.json)
echo "Blocked by $GATE: $REASON"
```

### Full Explanation with Evidence and Trace

```bash
# Get complete explanation with all details
stella explain block sha256:abc123... \
  --show-evidence \
  --show-trace \
  --replay-token \
  --format table
```

### Markdown for PR Comment

```bash
# Generate markdown for GitHub PR comment
stella explain block sha256:abc123... --format markdown --output comment.md

# Use with gh CLI
gh pr comment 123 --body-file comment.md
```

### Retrieve Evidence Artifacts

```bash
# Get explanation
stella explain block sha256:abc123... --show-evidence

# Retrieve specific evidence artifacts
stella evidence get vex:sha256:def456789abc123
stella evidence get reach:sha256:789abc123def456
```

### Verify Deterministic Replay

```bash
# Get replay token
REPLAY=$(stella explain block sha256:abc123... --format json | jq -r '.replayCommand')

# Execute replay verification
eval $REPLAY
```

---

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Artifact is NOT blocked (all gates passed) |
| `1` | Artifact IS blocked (one or more gates failed) |
| `2` | Error (artifact not found, API error, etc.) |

**CI/CD Integration:**

```bash
# Fail pipeline if artifact is blocked
if ! stella explain block sha256:abc123... --format json > /dev/null 2>&1; then
  EXIT_CODE=$?
  if [ $EXIT_CODE -eq 1 ]; then
    echo "ERROR: Artifact is blocked by policy"
    stella explain block sha256:abc123... --format markdown
    exit 1
  else
    echo "ERROR: Could not retrieve block status"
    exit 2
  fi
fi
```

---

## Evidence Types

The `explain block` command returns evidence artifacts that contributed to the gate decision:

| Type | Description | Source |
|------|-------------|--------|
| `VEX` | VEX (Vulnerability Exploitability eXchange) statement | VEX issuers, vendor security teams |
| `REACH` | Reachability analysis result | Static analysis, call graph analysis |
| `SBOM` | Software Bill of Materials | SBOM generators, build systems |
| `SCAN` | Vulnerability scan result | Scanner service |
| `ATTEST` | Attestation document | Attestor service, SLSA provenance |
| `POLICY` | Policy evaluation result | Policy engine |

---

## Determinism Guarantee

All output from `stella explain block` is **deterministic**:

1. **Same inputs produce identical outputs** - Given the same artifact digest and policy version, the output is byte-for-byte identical
2. **Evidence is sorted** - Evidence artifacts are sorted by timestamp (ascending)
3. **Trace is sorted** - Evaluation trace steps are sorted by step number
4. **Timestamps use ISO 8601** - All timestamps use ISO 8601 format with UTC offset
5. **JSON uses canonical ordering** - JSON properties are ordered consistently

This enables:
- **Replay verification** - Use the replay token to verify the decision can be reproduced
- **Audit trails** - Compare explanations across time
- **Cache validation** - Verify cached decisions match current evaluation

---

## Troubleshooting

### Artifact Not Found

```
Error: Artifact sha256:abc123... not found in registry or evidence store.
```

**Causes:**
- Artifact was never scanned
- Artifact digest is incorrect
- Artifact was deleted from registry

**Solutions:**
```bash
# Verify artifact exists
stella image inspect sha256:abc123...

# Scan the artifact
stella scan docker://myregistry/myimage@sha256:abc123...
```

### Not Blocked

```
Artifact sha256:abc123... is NOT blocked. All policy gates passed.
```

This means the artifact passed all policy evaluations. Exit code will be `0`.

### API Error

```
Error: Policy service unavailable
```

**Solutions:**
```bash
# Check connectivity
stella doctor --check check.policy.connectivity

# Use offline mode if available
stella explain block sha256:abc123... --offline
```

---

## See Also

- [Policy Commands](policy.md) - Policy management and testing
- [VEX Commands](vex.md) - VEX document management
- [Evidence Commands](evidence.md) - Evidence retrieval and verification
- [Verify Commands](verify.md) - Verdict verification and replay
- [Command Reference](reference.md) - Complete command reference