in-lockstep 0.1.0__tar.gz

in_lockstep-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,28 @@
+# Who has to approve a change here.
+#
+# This file names owners. It does not require anything on its own — GitHub only asks a code owner
+# for review when a ruleset or branch protection on `main` has "Require review from Code Owners"
+# turned on, with "Dismiss stale approvals" and "Require branches to be up to date" alongside it.
+# Without that, every line below is documentation. The setting lives in repository settings and is
+# not something this repository can grant itself.
+
+# Everything, unless something more specific below claims it. The last matching pattern wins.
+*                           @tpouyer
+
+# The parts where a mistake is not a bug but a policy change.
+#
+# `enforce:` compiles to workflow permissions, egress allow-lists, tool deny-lists and the credit
+# ceilings — the half of a guardrail a model cannot talk its way past. `library/` ships the baseline
+# guardrail inlined into every agent in every pipeline. A change to either reaches every consumer of
+# every pipeline built on this framework, which is a different kind of review from a bug fix.
+/src/lockstep/library/      @tpouyer
+/src/lockstep/emit/agentic.py   @tpouyer
+/actions/                   @tpouyer
+
+# Generated, but generated is not the same as unreviewed: these are what actually runs.
+/.github/workflows/         @tpouyer
+/.lockstep/                 @tpouyer
+
+# Licensing and attribution.
+/LICENSE                    @tpouyer
+/NOTICE                     @tpouyer

in_lockstep-0.1.0/.github/workflows/.gitattributes

@@ -0,0 +1,4 @@
+# GENERATED by lockstep — collapses generated files in pull request diffs.
+# Only what the compiler wrote: anything else in this directory belongs to the repository.
+*.lock.yml linguist-generated=true
+pipeline-ci.yml linguist-generated=true

in_lockstep-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.11'
+      - run: uv sync
+      - run: make ci

in_lockstep-0.1.0/.github/workflows/pipeline-ci.yml

@@ -0,0 +1,86 @@
+# GENERATED by lockstep 0.1.0 — do not edit.
+# Edit the spec, add an overlay, or run `lockstep eject` on this file.
+# sources: .lockstep/pipeline.yaml@411a460f
+# profile: repo
+name: pipeline-ci
+on:
+  pull_request:
+    paths:
+    - .lockstep/commands/**
+    - .lockstep/agents/**
+    - .lockstep/guardrails/**
+    - .lockstep/skills/**
+    - .lockstep/contexts/**
+    - .lockstep/profiles/**
+    - .lockstep/mcp/**
+    - .lockstep/overlays/**
+    - .lockstep/scripts/**
+    - .lockstep/tests/**
+    - .lockstep/pipeline.yaml
+    - .lockstep/.pipeline/**
+    - .github/workflows/**
+    - src/**
+    - pyproject.toml
+    - uv.lock
+  push:
+    branches:
+    - main
+  workflow_dispatch: {}
+permissions:
+  contents: read
+concurrency:
+  group: pipeline-ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  drift:
+    name: Drift gate
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      with:
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@v6
+    - name: Install the pinned compiler
+      run: uv tool install "."
+    - name: Recompile and compare
+      run: lockstep compile --check --semantic-diff --fail-on-blocking --base=origin/${{ github.event.pull_request.base.ref || 'main' }}
+  lint:
+    name: Spec quality
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      with:
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@v6
+    - name: Install the pinned compiler
+      run: uv tool install "."
+    - name: Lint the spec
+      run: lockstep lint
+  doctor:
+    name: Target readiness
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      with:
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@v6
+    - name: Install the pinned compiler
+      run: uv tool install "."
+    - name: Check target readiness
+      run: lockstep doctor --target=github-agentic
+  scripts:
+    name: Script tests
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+    - uses: astral-sh/setup-uv@v6
+    - name: Run the scripts' own tests
+      run: if [ -d .lockstep/tests ]; then uv run pytest .lockstep/tests -q; else echo "no .lockstep/tests directory"; fi

in_lockstep-0.1.0/.github/workflows/release-actions.yml

@@ -0,0 +1,96 @@
+# Tagging *is* publishing for a composite action.
+#
+# There is nothing to upload: `uses: in-lockstep/lockstep/actions/restore@<sha>` resolves against a
+# commit in this repository. So this workflow's job is not to publish the tag — it is to prove the
+# tag is safe to point at before anyone does, because the moment it exists, every consumer that runs
+# `lockstep pin` can resolve it into their lock file and it becomes what their pipelines execute.
+#
+# Tagged `actions-v*` rather than `v*` deliberately. If the actions shared the compiler's tags, every
+# compiler release would move the pin under consumers who use the actions and never changed them —
+# churn that teaches people to approve pin bumps without reading them, which is the exact habit the
+# drift gate exists to prevent.
+name: release-actions
+
+on:
+  push:
+    tags: ['actions-v*']
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Tag or commit to verify without releasing
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify the actions
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+
+      - name: Every action the compiler references exists and takes what it is given
+        # The contract test walks the compiled examples, collects every `uses:` naming a capability
+        # action, and checks the inputs against that action's own `action.yml`. A tag that fails
+        # this would be a tag whose actions reject the workflows the compiler writes for them.
+        run: uv run pytest tests/test_contract.py -q
+
+      - name: Actions are pinned to commits, not to tags
+        # A composite action that itself uses a floating tag hands the mutability straight back.
+        run: |
+          set -euo pipefail
+          floating=$(grep -rnE 'uses:\s+[^@]+@(v[0-9]|main|master)' actions/ || true)
+          if [ -n "$floating" ]; then
+            echo "these steps reference a movable ref:"; echo "$floating"; exit 1
+          fi
+          echo "every `uses:` inside actions/ is pinned to a commit"
+
+      - name: The tag names a version the actions actually changed at
+        if: startsWith(github.ref, 'refs/tags/actions-v')
+        # Cheap guard against tagging out of habit. If nothing under actions/ changed since the
+        # previous actions tag, consumers would take a pin bump that alters nothing they run.
+        run: |
+          set -euo pipefail
+          previous=$(git tag --list 'actions-v*' --sort=-v:refname | sed -n '2p')
+          if [ -z "$previous" ]; then echo "first actions tag; nothing to compare"; exit 0; fi
+          if git diff --quiet "$previous" HEAD -- actions/; then
+            echo "actions/ is unchanged since $previous — this tag would move consumers' pins for nothing"
+            exit 1
+          fi
+          git diff --stat "$previous" HEAD -- actions/
+
+  release:
+    name: Cut the release
+    needs: verify
+    if: startsWith(github.ref, 'refs/tags/actions-v')
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          fetch-depth: 0
+      - name: Publish the release notes, with the commit consumers will pin
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          sha=$(git rev-parse HEAD)
+          {
+            echo "Composite actions for pipelines compiled by lockstep."
+            echo
+            echo '```yaml'
+            echo "capabilities:"
+            echo "  actions: github.com/in-lockstep/lockstep/actions@${TAG}"
+            echo '```'
+            echo
+            echo "\`lockstep pin\` resolves that to \`${sha}\`, and every generated workflow"
+            echo "references the actions by that commit rather than by the tag."
+          } > notes.md
+          gh release create "$TAG" --title "actions $TAG" --notes-file notes.md

in_lockstep-0.1.0/.github/workflows/release-exec-image.yml

@@ -0,0 +1,132 @@
+# Building and publishing the image that compiled workflows run their deterministic steps in.
+#
+# Unlike the composite actions, this one really does publish: a `container:` in a generated workflow
+# names a registry, and nothing resolves until something has been pushed there. The output that
+# matters is not the tag — it is the **digest**. `lockstep compile` refuses to emit an image that is
+# not pinned by digest, so a rebuild can never change what an already-reviewed pipeline runs.
+#
+# Tagged `exec-v*`, on its own line from the compiler and from the actions, for the same reason:
+# a pin should move when the thing behind it moved.
+name: release-exec-image
+
+on:
+  push:
+    tags: ['exec-v*']
+  workflow_dispatch:
+    inputs:
+      push:
+        description: Push to the registry (otherwise build and test only)
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+env:
+  IMAGE: ghcr.io/in-lockstep/pipeline-exec
+
+jobs:
+  build:
+    name: Build, prove, publish
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write     # the release note carries the digest
+      packages: write     # ghcr.io
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+      - name: The package builds and its tests pass
+        # The image installs this package. A wheel that does not build is an image that fails at
+        # `docker build` after ten minutes of apt, and a package whose tests fail is worse: it
+        # builds, publishes, and every consumer's script step runs the regression.
+        run: |
+          set -euo pipefail
+          uv sync
+          uv run pytest packages/pipeline-exec -q
+          # The distribution is `in-lockstep-exec`, not `pipeline-exec`: the bare name belongs to an
+          # unrelated project on PyPI. The import name and the console script stay `pipeline_exec`.
+          uv build --package in-lockstep-exec --out-dir dist
+          test -f dist/in_lockstep_exec-*.whl
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the registry
+        if: startsWith(github.ref, 'refs/tags/exec-v') || inputs.push
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Build
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: packages/pipeline-exec
+          file: packages/pipeline-exec/docker/Dockerfile
+          # linux/amd64 only, deliberately: GitHub-hosted runners are x86_64, and a container job
+          # runs on the runner's architecture. An arm64 layer nobody pulls doubles the build for
+          # nothing. Add it when somebody runs a self-hosted arm64 fleet.
+          platforms: linux/amd64
+          push: ${{ startsWith(github.ref, 'refs/tags/exec-v') || inputs.push }}
+          load: ${{ !(startsWith(github.ref, 'refs/tags/exec-v') || inputs.push) }}
+          tags: |
+            ${{ env.IMAGE }}:${{ github.ref_name }}
+            ${{ env.IMAGE }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: The image can actually run a step
+        # A published image that cannot execute the commands the compiler writes into workflows is
+        # the failure this catches. `list-commands` is the introspection surface: it names every
+        # builtin, so a missing entry point fails here rather than in somebody's pipeline.
+        env:
+          PUBLISHED: ${{ startsWith(github.ref, 'refs/tags/exec-v') || inputs.push }}
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          set -euo pipefail
+          # Which reference to smoke-test is decided by whether the image was pushed, not by whether
+          # a digest exists. `load:` also produces a digest, but it names a manifest that only lives
+          # in the registry — so a digest reference is always resolved by pulling, and the dry run
+          # neither pushed nor logged in. It has to test the tag it loaded.
+          if [ "$PUBLISHED" = "true" ]; then
+            ref="${IMAGE}@${DIGEST}"
+          else
+            ref="${IMAGE}:${GITHUB_REF_NAME}"
+          fi
+          echo "smoke-testing $ref"
+          docker run --rm "$ref" pipeline-exec --version
+          docker run --rm "$ref" pipeline-exec list-commands
+          # The runtimes a `script:` step dispatches on by file extension.
+          docker run --rm --entrypoint sh "$ref" -c 'uv --version && node --version && ruby --version && go version && gh --version'
+
+      - name: Publish the digest, which is the thing consumers pin
+        if: startsWith(github.ref, 'refs/tags/exec-v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          set -euo pipefail
+          {
+            echo "The executor image for pipelines compiled by lockstep."
+            echo
+            echo '```yaml'
+            echo "capabilities:"
+            echo "  exec-image: ${IMAGE}"
+            echo '```'
+            echo
+            echo "Then pin it. The tag above exists for humans; the digest is what runs:"
+            echo
+            echo '```bash'
+            echo "lockstep pin --exec-digest=${DIGEST}"
+            echo '```'
+            echo
+            echo "\`lockstep compile\` refuses to emit an image that is not pinned by digest, so"
+            echo "rebuilding \`${TAG}\` cannot change what an already-reviewed pipeline runs."
+          } > notes.md
+          gh release create "$TAG" --title "executor image $TAG" --notes-file notes.md
+          echo "### \`$DIGEST\`" >> "$GITHUB_STEP_SUMMARY"

in_lockstep-0.1.0/.github/workflows/release-python.yml

@@ -0,0 +1,133 @@
+# Publishing the two Python distributions this repository builds.
+#
+# `in-lockstep` is the compiler and `in-lockstep-exec` is the runtime, and a compiled pipeline
+# installs both **by name from a public index**: the drift-gate job runs
+# `uv tool install "in-lockstep=="`, and an eval job that materializes inherited definitions installs
+# the executor alongside it because the exec image deliberately does not carry the compiler. So
+# until these exist on PyPI, a consumer repository can resolve every action and pull the image and
+# still not run.
+#
+# **No API token exists anywhere in this.** Publication is by Trusted Publishing: PyPI verifies a
+# short-lived OIDC credential minted by Actions for this repository, this workflow and this
+# environment. There is no secret to leak, rotate, or scope wrongly — which is the same argument
+# the rest of the framework makes about agents never holding credentials.
+#
+# The environment is **per distribution**, which is not decoration. PyPI identifies a publisher by
+# owner, repository, workflow and environment together, and refuses to register two projects behind
+# an identical configuration — otherwise one credential would speak for both, and a workflow allowed
+# to publish the runtime could publish the compiler. Naming the environment after the project is
+# what keeps each credential scoped to the one thing it may upload.
+#
+# Tagged `v*`, the compiler's own line. `actions-v*` and `exec-v*` stay separate so a pin moves when
+# the thing behind it moved.
+name: release-python
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Upload to PyPI (otherwise build and prove only)
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and prove
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.11'
+
+      - name: The tag names the version being published
+        # A tag and a version that disagree publish something nobody asked for, under a name nobody
+        # can withdraw: PyPI never lets a version be reused, even after a delete.
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          for manifest in pyproject.toml packages/pipeline-exec/pyproject.toml; do
+            version=$(grep -m1 '^version = ' "$manifest" | cut -d'"' -f2)
+            if [ "$version" != "$tag" ]; then
+              echo "$manifest is $version, but the tag says $tag"; exit 1
+            fi
+          done
+          echo "both distributions are $tag"
+
+      - run: uv sync
+      - name: The suite passes
+        run: uv run pytest -q
+
+      - name: Build both distributions
+        # Into separate directories: each PyPI project is a separate Trusted Publishing exchange, and
+        # an upload pointed at a directory would otherwise carry the other project's files with it.
+        run: |
+          set -euo pipefail
+          uv build --package in-lockstep --out-dir dist/in-lockstep
+          uv build --package in-lockstep-exec --out-dir dist/in-lockstep-exec
+          uvx twine check dist/*/*
+
+      - name: A clean install carries what is not Python
+        # The failure this exists for: the compiler ships five pipelines as markdown under
+        # `lockstep/library/`, and the executor ships Jinja report templates. Neither is a `.py`
+        # file, so a packaging change can drop them while every test in this repository still passes
+        # — they are read from the source tree here and from site-packages everywhere else.
+        # `init --adopt all` reads the library, so it fails if the library did not travel.
+        run: |
+          set -euo pipefail
+          python3 -m venv /tmp/proof
+          /tmp/proof/bin/pip install -q dist/in-lockstep/*.whl dist/in-lockstep-exec/*.whl
+          /tmp/proof/bin/lockstep --version
+          /tmp/proof/bin/pipeline-exec --version
+          /tmp/proof/bin/pipeline-exec list-commands > /dev/null
+          mkdir -p /tmp/proof-repo && cd /tmp/proof-repo
+          /tmp/proof/bin/lockstep init --name proof --adopt all
+          test -d .lockstep || test -f pipeline.yaml
+          /tmp/proof/bin/lockstep fetch
+          echo "the shipped library survived packaging"
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish ${{ matrix.project }}
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') || inputs.publish
+    runs-on: ubuntu-24.04
+    # pypi-in-lockstep and pypi-in-lockstep-exec. Each must match the environment recorded in that
+    # project's publisher on PyPI, or the exchange is refused.
+    environment: pypi-${{ matrix.project }}
+    permissions:
+      id-token: write     # mint the OIDC credential PyPI verifies; nothing else is needed
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [in-lockstep, in-lockstep-exec]
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: distributions
+          path: dist
+      - name: Upload to PyPI
+        # v1.14.2 or newer, and the floor is load-bearing rather than hygiene: it is the first
+        # release carrying Twine 7, and Twine below that rejects core metadata 2.5 outright. Both
+        # distributions are 2.5, because hatchling emits PEP 639 `License-Expression` for the
+        # `license = "Apache-2.0"` these manifests declare.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+        with:
+          packages-dir: dist/${{ matrix.project }}
+          # One tag publishes both distributions, and they do not always both move. A version already
+          # on PyPI is the normal case for the one that did not change, not a failure.
+          skip-existing: true
+          print-hash: true

in_lockstep-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+
+# Fetched by `lockstep fetch` at the commit pins.lock records.
+**/.pipeline/inherited/

in_lockstep-0.1.0/.lockstep/.pipeline/compile-manifest.json

@@ -0,0 +1,19 @@
+{
+  "compiler": "0.1.0",
+  "files": {
+    ".github/workflows/.gitattributes": {
+      "sha": "8dd12516",
+      "sources": []
+    },
+    ".github/workflows/pipeline-ci.yml": {
+      "sha": "0b0c8631",
+      "sources": []
+    },
+    ".lockstep/SECRETS.md": {
+      "sha": "3864c66c",
+      "sources": []
+    }
+  },
+  "pipeline": "lockstep",
+  "spec": 1
+}

in_lockstep-0.1.0/.lockstep/.pipeline/pins.lock

@@ -0,0 +1,15 @@
+{
+  "capabilities": {
+    "exec": {
+      "image": "",
+      "package": "pipeline-exec"
+    }
+  },
+  "external": {
+    "actions/checkout": {
+      "sha": "11d5960a326750d5838078e36cf38b85af677262",
+      "tag": "v4"
+    }
+  },
+  "inherits": {}
+}

in_lockstep-0.1.0/.lockstep/SECRETS.md

@@ -0,0 +1,10 @@
+<!-- GENERATED by lockstep — do not edit. -->
+
+# Secrets and variables
+
+Every secret and variable this pipeline needs, by environment.
+
+## Profile `repo` — environment `(repository level)`
+
+```bash
+```

in_lockstep-0.1.0/.lockstep/pipeline.yaml

@@ -0,0 +1,27 @@
+spec: 1
+name: lockstep
+
+# This repository compiles its own drift gate.
+#
+# Everything else here is a pipeline repository that installs a released compiler. This one *is* the
+# compiler, which changes exactly one thing and it is the thing that matters: the output is a
+# function of the spec **and** of `src/`. So `compiler` points at the checkout rather than at a
+# release — a gate that installed the published `lockstep` would recompile a pull request's spec
+# with the previous pull request's compiler and pass — and `watch` puts the compiler's own source on
+# the trigger, because a change to the emitter is the change most worth recompiling.
+#
+# No `actions`, `exec` or `exec-image`: this pipeline has no steps, so its output names no composite
+# action and pulls no container. When it grows one, those get declared and pinned like anywhere else.
+
+capabilities:
+  compiler: "."
+
+targets:
+  github-agentic:
+    out: .github/workflows
+    default-runs-on: ubuntu-24.04
+    profiles: [repo]
+    watch:
+      - src/**
+      - pyproject.toml
+      - uv.lock

in_lockstep-0.1.0/.lockstep/profiles/repo.md

@@ -0,0 +1,7 @@
+---
+name: repo
+description: This repository, checked out by the workflow that runs the gate
+github:
+  deploy:
+    mode: external
+---