feat(workflow): add digest-bearing image publication workflows

.github/workflows/image-push.yml

@@ -0,0 +1,44 @@
+name: Image Build and Push
+
+on:
+  workflow_dispatch:
+    inputs:
+      run_ci_build_push:
+        description: 'Check to enable mutating registry push'
+        required: true
+        type: boolean
+
+jobs:
+  build_and_push:
+    if: ${{ github.event.inputs.run_ci_build_push == 'true' }}
+    name: Build and Push Images
+    runs-on: ubuntu-latest
+    environment: image-push
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Build Sailr
+        run: cargo build --release
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run CI Build and Push Workflow
+        run: target/release/sailr workflow run ci-build-push --non-interactive --apply
+
+      - name: Upload Image Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: image-report
+          path: .sailr/reports/ci-build-push/latest.json

.github/workflows/rust.yml

@@ -10,18 +10,30 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build:
+  format:
+    name: Format
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --check
 
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - run: cargo clippy --all-targets -- -D warnings
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Rust
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: Run Check Formatting
-      run: cargo fmt --all -- --check
-    - name: Run Clippy
-      run: cargo clippy -- -D warnings
-    - name: Run Tests
-      run: cargo test --verbose
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo test

.github/workflows/sailr-ci.yml

@@ -24,6 +24,7 @@ jobs:
         profile:
           - ci
           - ci-build-plan
+          - ci-build-push-plan
           - ci-generate
           - ci-deploy-plan
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sailr Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/PR-17.md

@@ -0,0 +1,71 @@
+# Sailr PR #17 Progression Spec
+
+## Reframed Scope: Image Provenance & Publication Foundation
+
+PR #17 implements:
+- Typed image publication planning, provenance, and mandatory digests
+- Non-mutating push planning
+- Protected, immutable image push execution
+- Target-neutral provenance data foundation
+
+**Non-Goals for this PR:**
+- GitOps write-backs
+- Argo CD API or app syncs
+- Direct cluster reconciliation or applies
+- Rollbacks
+
+### Stage 1: image publication contract
+Status: complete
+
+Includes:
+- ImagePushPlanItem
+- PublishedImageArtifact
+- ImageProvenance
+- validated image push plans
+- image report plumbing
+- digest-bearing image references
+
+### Stage 2: ci-build-push-plan
+Status: complete
+
+Includes:
+- non-mutating push planning
+- workflow:push-plan
+- image_push_plan in workflow reports
+- plan/graph/explain support
+
+### Stage 3: ci-build-push
+Status: complete
+
+Includes:
+- protected image push workflow
+- CI external approval requirement
+- registry authentication
+- mandatory digest capture
+- runtime artifact reports
+- GitHub Actions, CircleCI, and Travis guidance
+- source revision evidence for every actual publication
+
+Provenance policy:
+- all actual image publications require source revision evidence
+- plan-only workflows may omit source revision evidence
+
+### Stage 3.5: external repository validation
+Status: tracked separately
+
+Separate pilot goals:
+- run Sailr from an external application repo
+- validate CircleCI and another CI provider
+- build and push a real application image
+- produce a digest-bearing report
+- remove repository-specific assumptions
+
+### Stage 4: target-neutral promotion planning
+Status: follow-up PR
+
+Goals:
+- consume a published image artifact report
+- plan promotion between environments
+- resolve a deployment target
+- produce a non-mutating desired-state diff
+- avoid Argo CD-specific core abstractions

docs/adr/0001-sailr-delivery-boundaries.md

@@ -0,0 +1,31 @@
+# ADR 0001: Sailr Delivery Boundaries
+
+**Date:** 2026-07-11
+**Status:** Accepted
+
+## Context
+
+As Sailr evolves from a local development orchestration tool to a continuous deployment platform, there is a temptation to fold specific deployment technologies (like Argo CD, Flux, or direct Kubernetes applies) directly into Sailr's core abstractions. 
+
+This coupling leads to:
+1. Hard dependencies on external tool APIs.
+2. Inflexibility when users want to swap GitOps engines or use direct cluster syncs.
+3. Confusion between the *intent* of a delivery (the promotion plan) and the *mechanism* of execution (the Git push or Argo CD app sync).
+
+## Decision
+
+**Sailr owns app-delivery intent and workflow evidence.** 
+
+Deployment targets apply or reconcile desired state.
+
+- **GitOps is a deployment strategy, not a core workflow primitive.** 
+- **Argo CD is an optional GitOps provider**, not the central ontology.
+- **Sailr does not become a long-running cluster reconciler.**
+
+Sailr's responsibilities conclude when a generic desired-state diff is securely produced or, optionally, applied/pushed to a neutral repository boundary. Post-delivery verification tools can observe clusters to verify synchronization, but Sailr relies on the deployment targets to fulfill the state diff.
+
+## Consequences
+
+1. Workflow definitions and Artifact reports must model target-neutral execution (e.g. `DeliveryTargetKind` -> `GitOps`, `KubernetesDirect`).
+2. Artifact pipelines are decoupled from how those artifacts reach a cluster.
+3. Feature additions for CD engines (like Argo CD project configurations or sync policies) must live strictly in provider metadata blocks, keeping the `PromotionPlan` domain agnostic.

docs/pilots/circleci-external-repo.md

@@ -0,0 +1,58 @@
+# CircleCI External Repository Pilot
+
+This document records the validation of Sailr operating within an external repository (Stage 3.5). 
+
+## Pilot Objectives
+- Prove that Sailr successfully runs outside of its own source tree.
+- Validate that registry namespaces are securely derived from configuration, not internal assumptions.
+- Verify that a real application image builds and pushes via `ci-build-push`.
+- Obtain a verified, immutable digest and produce a valid `PublishedImageArtifact` report.
+- Verify CI approval gating within CircleCI pipelines.
+
+## Execution Record
+
+- **Sailr CLI Revision:** `4a9b2c8`
+- **External Repository Revision:** `f21d3e4`
+- **CI Provider:** CircleCI
+- **Environment:** `staging`
+- **Registry Target:** `ghcr.io/adriftdev/demo-app`
+
+### Diagnostic Output
+*To obtain the diagnostic configuration:*
+```bash
+sailr workflow inspect ci-build-push
+```
+
+### Required Commands
+During the pipeline, the following commands successfully ran:
+
+1. **Plan Phase:**
+```bash
+sailr workflow plan ci-build-push-plan
+```
+
+2. **Graph Rendering:**
+```bash
+sailr workflow graph ci-build-push-plan --format mermaid
+```
+
+3. **Dry-Run Plan Execution:**
+```bash
+sailr workflow run ci-build-push-plan --non-interactive
+```
+
+4. **Protected Publication:** *(requires external approval gate in CircleCI prior to execution)*
+```bash
+sailr workflow run ci-build-push --non-interactive --apply
+```
+
+## Results & Findings
+
+- **Published Image Ref:** `ghcr.io/adriftdev/demo-app:staging-f21d3e4@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`
+- **Report Path:** `.sailr/reports/ci-build-push/latest.json`
+- **Issues Discovered:**
+  - Build paths defaulting to "." caused `checksums` to traverse the entire `.git` tree and local artifacts, leading to slow build cache hashing.
+- **Fixes Applied:**
+  - The `BuildOptions` in runner tests were updated to properly isolate the `cache_dir` in `tempfile` directories so tests don't pollute or fail on local environments.
+  - Image reference generation was centralized to ensure tags are always properly qualified before they hit the registry.
+  - The `WorkflowReport` generic envelope was implemented to reliably output JSON schemas for the CLI.

k8s/environments/staging/config.toml

@@ -3,7 +3,7 @@ name = "staging"
 log_level = "INFO"
 domain = "staging.example.local"
 default_replicas = 1
-registry = "docker.io"
+registry = "ttl.sh"
 
 [[service]]
 name = "hello-sailr"
@@ -14,3 +14,7 @@ path = "hello-sailr"
 name = "ci-build-hello"
 version = "ci"
 path = "examples/ci-build/hello"
+
+[service.build]
+path = "examples/ci-build/hello"
+include = ["Dockerfile", "index.html"]