# stella policy — Command Guide

## Overview

The `stella policy` command group provides comprehensive policy management capabilities for Policy Studio, including creation, simulation, workflow management, and lifecycle operations.

## Commands

### Policy Creation & Scaffolding

```bash
# Create a new policy from a template
stella policy new <name> [--template <template>] [--output <path>] [--description <desc>] [--tags <tag1,tag2>] [--shadow-mode] [--create-fixtures] [--git-init]
```

**Templates:** `basic`, `sbom-gate`, `vex-precedence`, `reachability`, `secret-detection`, `license-compliance`, `supply-chain`

### Policy Simulation (CLI-POLICY-27-003)

```bash
# Simulate policy changes with enhanced options
stella policy simulate <policy-id> \
  [--base <version>] \
  [--candidate <version>] \
  [--sbom <id1,id2,...>] \
  [--env key=value] \
  [--mode quick|batch] \
  [--sbom-selector <pattern>] \
  [--heatmap] \
  [--manifest-download] \
  [--reachability-state <id:state>] \
  [--reachability-score <id:score>] \
  [--with-exception <exc-id>] \
  [--without-exception <exc-id>] \
  [--explain] \
  [--fail-on-diff] \
  [--format json|table|markdown] \
  [--output <path>]
```

**Options:**
| Flag | Description |
|------|-------------|
| `--mode quick\|batch` | Simulation mode: `quick` samples SBOMs, `batch` evaluates all matching |
| `--sbom-selector` | SBOM selector pattern (e.g., `registry:docker.io/*`, `tag:production`). Repeatable |
| `--heatmap` | Include severity heatmap summary in output |
| `--manifest-download` | Request manifest download URI for offline analysis |
| `--reachability-state` | Override reachability state (format: `CVE-XXXX:reachable`). Repeatable |
| `--reachability-score` | Override reachability score (format: `CVE-XXXX:0.85`). Repeatable |
| `--format markdown` | Generate CI-friendly markdown report |

### Policy Workflow (CLI-POLICY-27-002)

```bash
# Bump policy version
stella policy version bump <policy-id> [--changelog <message>] [--major|--minor|--patch]

# Submit policy for review
stella policy submit <policy-id> [--version <ver>] [--reviewers <user1,user2>] [--changelog <message>]

# Add review comment
stella policy review comment <policy-id> [--version <ver>] --comment <text> [--line <num>] [--file <path>]

# Approve policy review
stella policy approve <policy-id> [--version <ver>] [--comment <text>]

# Reject policy review
stella policy reject <policy-id> [--version <ver>] --reason <text>

# Get review status
stella policy review status <policy-id> [--version <ver>]
```

### Policy Lifecycle (CLI-POLICY-27-004)

```bash
# Publish policy
stella policy publish <policy-id> [--version <ver>] [--sign] [--attestation-type <type>] [--dry-run]

# Promote policy to environment
stella policy promote <policy-id> [--version <ver>] --env <environment> [--canary <percentage>] [--dry-run]

# Rollback policy
stella policy rollback <policy-id> [--to-version <ver>] [--reason <text>] [--force]

# Sign policy
stella policy sign <policy-id> [--version <ver>] [--key-id <key>] [--attestation-type <type>]

# Verify policy signature
stella policy verify-signature <policy-id> [--version <ver>] [--check-rekor]
```

### Policy History & Explain (CLI-POLICY-23-006)

```bash
# Get policy history
stella policy history <policy-id> [--limit <num>] [--since <date>] [--until <date>]

# Explain policy decision
stella policy explain <policy-id> [--version <ver>] [--finding-id <id>] [--verbose]
```

### Policy Activation

```bash
# Activate an approved policy revision
stella policy activate <policy-id> --version <ver> [--environment <env>] [--force] [--dry-run]
```

## Common Flags

| Flag | Description |
|------|-------------|
| `--tenant` / `-t` | Tenant context for the operation |
| `--json` | Output as JSON |
| `--verbose` / `-v` | Enable verbose logging |
| `--offline` | Forbid network calls; use cached bundles only |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 4 | Input validation error |
| 5 | Network required but offline mode enabled |
| 20 | Differences detected with `--fail-on-diff` |
| 130 | Operation cancelled by user |

## JSON Schemas

### PolicySimulationResult

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "diff": {
      "type": "object",
      "properties": {
        "schemaVersion": { "type": "string" },
        "added": { "type": "integer" },
        "removed": { "type": "integer" },
        "unchanged": { "type": "integer" },
        "bySeverity": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "up": { "type": "integer" },
              "down": { "type": "integer" }
            }
          }
        },
        "ruleHits": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "ruleId": { "type": "string" },
              "ruleName": { "type": "string" },
              "up": { "type": "integer" },
              "down": { "type": "integer" }
            }
          }
        }
      }
    },
    "explainUri": { "type": "string" },
    "heatmap": {
      "type": "object",
      "properties": {
        "buckets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "severity": { "type": "string" },
              "count": { "type": "integer" },
              "percentage": { "type": "number" }
            }
          }
        },
        "total": { "type": "integer" }
      }
    },
    "manifestDownloadUri": { "type": "string" },
    "manifestDigest": { "type": "string" }
  }
}
```

### PolicyReviewSummary

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "policyId": { "type": "string" },
    "version": { "type": "integer" },
    "status": { "type": "string", "enum": ["pending", "approved", "rejected", "changes_requested"] },
    "submittedBy": { "type": "string" },
    "submittedAt": { "type": "string", "format": "date-time" },
    "reviewers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "userId": { "type": "string" },
          "status": { "type": "string" },
          "reviewedAt": { "type": "string", "format": "date-time" }
        }
      }
    },
    "comments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "commentId": { "type": "string" },
          "author": { "type": "string" },
          "text": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "line": { "type": "integer" },
          "file": { "type": "string" }
        }
      }
    }
  }
}
```

## CI/CD Integration Examples

### GitHub Actions

```yaml
name: Policy Simulation
on:
  pull_request:
    paths:
      - 'policies/**'

jobs:
  simulate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Stella CLI
        run: |
          curl -sSL https://get.stellaops.io | bash

      - name: Simulate Policy Changes
        run: |
          stella policy simulate P-7 \
            --base $(git merge-base HEAD origin/main) \
            --candidate HEAD \
            --mode batch \
            --heatmap \
            --format markdown \
            --output simulation-report.md \
            --fail-on-diff

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: policy-simulation-report
          path: simulation-report.md
```

### GitLab CI

```yaml
policy-simulate:
  stage: test
  script:
    - stella policy simulate P-7 --mode quick --heatmap --json > simulation.json
    - |
      if [ $(jq '.diff.added + .diff.removed' simulation.json) -gt 0 ]; then
        echo "Policy changes detected"
        stella policy simulate P-7 --format markdown --output report.md
        exit 20
      fi
  artifacts:
    paths:
      - simulation.json
      - report.md
    when: always
```

### Azure DevOps

```yaml
- task: Bash@3
  displayName: 'Policy Simulation'
  inputs:
    targetType: 'inline'
    script: |
      stella policy simulate P-7 \
        --mode batch \
        --sbom-selector "registry:$(ACR_REGISTRY)/*" \
        --heatmap \
        --json \
        --output $(Build.ArtifactStagingDirectory)/simulation.json
```

## Determinism Rules

- Sort evaluation results by subject key
- Timestamps use UTC ISO-8601 format
- No inferred verdicts beyond Policy Engine response
- Hashes computed with SHA-256

## Offline/Air-Gap Notes

- When `--offline` is set, evaluation uses locally cached bundles and subject artifacts
- Fails with exit code 5 if network would be needed
- Trust roots loaded from `STELLA_TRUST_ROOTS` environment variable when verifying signed bundles
- Signature verification can use local Rekor mirror via `STELLA_REKOR_MIRROR`

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STELLAOPS_BACKEND_URL` | Backend API URL |
| `STELLA_OFFLINE` | Set to `1` to enable offline mode |
| `STELLA_TRUST_ROOTS` | Path to trust roots for signature verification |
| `STELLA_REKOR_MIRROR` | Local Rekor transparency log mirror URL |
| `STELLAOPS_TENANT` | Default tenant context |