git.stella-ops.org/docs/task-packs/spec.md

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

Task Pack Specification (Sprint 43 Draft)

The Task Pack specification defines a deterministic, auditable format that enables operators to encode multi-step maintenance, validation, and deployment workflows. Packs are executed by the Task Runner service, distributed through the Packs Registry, and invoked via the StellaOps CLI (stella pack ...) or Orchestrator integrations.

---

1 · Goals & Scope

• Deterministic execution. Identical inputs yield identical run graphs, output manifests, and evidence bundles across environments (online, sealed, or offline).
• Secure-by-default. Pack metadata must capture provenance, signatures, RBAC requirements, and secret usage; execution enforces tenant scopes and approvals.
• Portable. Packs are distributed as signed OCI artifacts or tarballs that work in connected and air-gapped deployments, including Offline Kit mirrors.
• Composable. Packs can reference reusable steps, expressions, and shared libraries without sacrificing determinism or auditability.

Non-goals: full-blown workflow orchestration, unbounded scripting, or remote code injection. All logic is declarative and constrained to Task Runner capabilities.

---

2 · Terminology

Term	Definition
Pack manifest	Primary YAML document (pack.yaml) describing metadata, inputs, steps, policies, and evidence expectations.
Step	Atomic unit of work executed by Task Runner (e.g., command, API call, policy gate, approval). Steps can be sequential or parallel.
Expression	Deterministic evaluation (JMESPath-like) used for branching, templating, and conditionals.
Policy gate	Declarative rule that blocks execution until conditions are met (e.g., approval recorded, external signal received).
Artifact	File, JSON blob, or OCI object produced by a step, referenced in manifests and evidence bundles.
Pack bundle	Distribution archive (.stella-pack.tgz or OCI ref) containing manifest, assets, schemas, and provenance metadata.

---

3 · Pack Layout

my-pack/
 ├─ pack.yaml                  # Required manifest
 ├─ assets/                    # Optional static assets (scripts, templates)
 ├─ schemas/                   # JSON schemas for inputs/outputs
 ├─ docs/                      # Markdown docs rendered in Console/CLI help
 ├─ provenance/                # DSSE statements, SBOM, attestations
 └─ README.md                  # Author-facing summary (optional)

Publishing via Packs Registry or OCI ensures the directory is canonical and hashed.

---

4 · Manifest Schema (v1.0)

apiVersion: stellaops.io/pack.v1
kind: TaskPack
metadata:
  name: sbom-remediation
  version: 1.3.0
  description: >
    Audit SBOM drift, quiet high-risk findings, and export mitigation evidence.
  tags: [sbom, remediation, policy]
  tenantVisibility: ["west-prod", "east-stage"]   # optional allowlist
  maintainers:
    - name: Jane Doe
      email: jane@example.com
  license: AGPL-3.0-or-later
  annotations:
    imposedRuleReminder: true

spec:
  inputs:
    - name: sbomBundle
      type: object
      schema: schemas/sbom-bundle.schema.json
      required: true
    - name: dryRun
      type: boolean
      default: false
  secrets:
    - name: jiraToken
      scope: Packs.Run    # Authority scope required
      description: Optional token for ticket automation
  approvals:
    - id: security-review
      grants: ["Packs.Approve"]
      expiresAfter: PT4H
      reasonTemplate: "Approve remediation for SBOM {{ inputs.sbomBundle.metadata.image }}"
  steps:
    - id: validate-input
      run:
        uses: builtin:validate-schema
        with:
          target: "{{ inputs.sbomBundle }}"
          schema: schemas/sbom-bundle.schema.json
    - id: plan-remediation
      when: "{{ not inputs.dryRun }}"
      run:
        uses: builtin:policy-simulate
        with:
          sbom: "{{ inputs.sbomBundle }}"
          policy: "policies/remediation.yaml"
    - id: approval-gate
      gate:
        approval: security-review
        message: "Security must approve remediation before changes apply."
    - id: apply-remediation
      run:
        uses: builtin:cli-command
        with:
          command: ["stella", "policy", "promote", "--from-pack"]
    - id: export-evidence
      run:
        uses: builtin:evidence-export
        with:
          includeArtifacts: ["{{ steps.plan-remediation.outputs.planPath }}"]
  outputs:
    - name: evidenceBundle
      type: file
      path: "{{ steps.export-evidence.outputs.bundlePath }}"
  success:
    message: "Remediation applied; evidence bundle ready."
  failure:
    retries:
      maxAttempts: 1
      backoffSeconds: 0
    message: "Remediation failed; see evidence bundle for context."

4.1 Field Summary

Field	Description	Requirements
metadata	Human-facing metadata; used for registry listings and RBAC hints.	name (DNS-1123), version (SemVer), description ≤ 2048 chars.
spec.inputs	Declarative inputs validated at plan time.	Must include type; custom schema optional but recommended.
spec.secrets	Secrets requested at runtime; never stored in pack bundle.	Each secret references Authority scope; CLI prompts or injects from profiles.
spec.approvals	Named approval gates with required grants and TTL.	ID unique per pack; grants map to Authority roles.
spec.steps	Execution graph; each step is run, gate, parallel, or map.	Steps must declare deterministic uses module and id.
spec.outputs	Declared artifacts for downstream automation.	type can be file, object, or url; path/expression required.
success / failure	Messages + retry policy.	failure.retries.maxAttempts + backoffSeconds default to 0.

---

5 · Step Types

Type	Schema	Notes
run	Executes a built-in module (builtin:*) or registry-provided module.	Modules must be deterministic, side-effect constrained, and versioned.
parallel	Executes sub-steps concurrently; maxParallel optional.	Results aggregated; failures trigger abort unless continueOnError.
map	Iterates over deterministic list; each iteration spawns sub-step.	Sequence derived from expression result; ordering stable.
gate.approval	Blocks until approval recorded with required grants.	Supports autoExpire to cancel run on timeout.
gate.policy	Calls Policy Engine to ensure criteria met (e.g., no critical findings).	Fails run if gate not satisfied.

when expressions must be pure (no side effects) and rely only on declared inputs or prior outputs.

---

6 · Determinism & Validation

1. Plan phase (stella pack plan, TaskRunner.Plan API) parses manifest, resolves expressions, validates schemas, and emits canonical graph with hash.
2. Simulation compares plan vs dry-run results, capturing differences in planDiff. Required for approvals in sealed environments.
3. Execution uses plan hash to ensure runtime graph matches simulation. Divergence aborts run.
4. Evidence: Task Runner emits DSSE attestation referencing plan hash, input digests, and output artifacts.

Validation pipeline:

pack.yaml ──▶ schema validation ──▶ expression audit ──▶ determinism guard ──▶ signing

Packs must pass CLI validation before publishing.

---

7 · Signatures & Provenance

• Pack bundles are signed with cosign (keyless Fulcio/KMS supported) and optionally DSSE envelopes.
• provenance/ directory stores signed statements (SLSA Build L1+) linking source repo, CI run, and manifest hash.
• Registry verifies signatures on push/pull; Task Runner refuses unsigned packs unless in development mode.
• Attestations include:
  • Pack manifest digest (sha256)
  • Pack bundle digest
  • Build metadata (git.ref, ci.workflow, cli.version)

---

8 · RBAC & Scopes

Authority scopes introduced by AUTH-PACKS-41-001:

Scope	Purpose
Packs.Read	Discover packs, download manifests.
Packs.Write	Publish/update packs in registry (requires signature).
Packs.Run	Execute packs via CLI/Task Runner.
Packs.Approve	Fulfil approval gates defined in packs.

Task Runner enforces scopes per tenant; pack metadata may further restrict tenant visibility (metadata.tenantVisibility).

---

9 · Observability & Evidence

• Metrics: pack_run_duration_seconds, pack_step_retry_total, pack_gate_wait_seconds.
• Logs: Structured JSON per step with scrubbed inputs (secretMask applied).
• Timeline events: pack.started, pack.approval.requested, pack.approval.granted, pack.completed.
• Evidence bundle includes:
  • Plan manifest (canonical JSON)
  • Step transcripts (redacted)
  • Artifacts manifest (sha256, size)
  • Attestations references

---

10 · Compatibility Matrix

CLI Version	Pack API	Task Runner	Notes
2025.10.x	pack.v1	Runner build >=2025.10.0	Approvals optional, loops disabled.
2025.12.x	pack.v1	Runner build >=2025.12.0	Approvals resume, secrets injection, localization strings.
Future	pack.v2	TBD	Will introduce typed outputs & partial replay (track in Epic 13).

CLI enforces compatibility: running pack with unsupported features yields ERR_PACK_UNSUPPORTED.

---

11 · Publishing Workflow

1. Author pack (pack.yaml, assets, docs).
2. Run stella pack validate (schema + determinism).
3. Generate bundle: stella pack build --output my-pack.stella-pack.tgz.
4. Sign: cosign sign-blob my-pack.stella-pack.tgz.
5. Publish: stella pack push registry.example.com/org/my-pack:1.3.0.
6. Registry verifies signature, records provenance, and exposes pack via API.

---

12 · Compliance Checklist

• Manifest schema documented for all fields, including approvals, secrets, and outputs.
• Determinism requirements outlined with plan/simulate semantics and CLI validation steps.
• Signing + provenance expectations spelled out with cosign/DSSE references.
• RBAC scopes (Packs.*) and tenant visibility rules captured.
• Observability (metrics, logs, evidence) described for Task Runner integrations.
• Compatibility matrix enumerates CLI/Runner requirements.
• Publishing workflow documented with CLI commands.
• Imposed rule reminder included at top of document.

---

Last updated: 2025-10-27 (Sprint 43).