> **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) ```yaml 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: ```text 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).*