steuermaschine 0.0.1__tar.gz

steuermaschine-0.0.1/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build
+    groups:
+      python:
+        patterns: ["*"]

steuermaschine-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0 # gitleaks scans the full history; cz checks the pushed commits
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.5"
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install gitleaks
+        run: |
+          curl -sSfL -o gitleaks.tgz https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  gitleaks.tgz" | sha256sum -c -
+          tar -xzf gitleaks.tgz -C /usr/local/bin gitleaks && rm gitleaks.tgz
+      - run: make install
+      - name: Private-term deny-list (tree and commit messages)
+        # The list lives in the repository secret PRIVATE_TERMS, never in the repository. On main a missing secret
+        # fails closed; on a pull request from a fork (no secrets) it is skipped with a notice.
+        env:
+          CONFIDENTIAL_TERMS: ${{ secrets.PRIVATE_TERMS }}
+          BEFORE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+        run: |
+          if [ -z "$CONFIDENTIAL_TERMS" ]; then
+            if [ "$GITHUB_REF" = refs/heads/main ]; then echo "::error::PRIVATE_TERMS secret missing"; exit 1; fi
+            echo "::notice::PRIVATE_TERMS not available; term guard skipped"; exit 0
+          fi
+          uv run --script scripts/check_confidentiality.py --require
+          case "$BEFORE" in ""|0000000000000000000000000000000000000000) BEFORE=$(git merge-base origin/main HEAD) ;; esac
+          if [ "$GITHUB_REF" = refs/heads/main ]; then range=HEAD; else range="$BEFORE..HEAD"; fi
+          uv run --script scripts/check_confidentiality.py --require --messages "$range"
+      - name: Conventional Commits (the commits this push or PR adds)
+        env:
+          BEFORE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+        run: |
+          case "$BEFORE" in ""|0000000000000000000000000000000000000000) BEFORE=$(git merge-base origin/main HEAD) ;; esac
+          if [ -n "$(git rev-list "$BEFORE..HEAD")" ]; then uv run cz check --rev-range "$BEFORE..HEAD"; fi
+      - run: make check
+      - run: make audit
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: coverage
+          path: coverage.xml
+          if-no-files-found: ignore
+      - name: Coverage summary
+        run: |
+          pct=$(python3 -c "import xml.etree.ElementTree as E; r=E.parse('coverage.xml').getroot().get; print(int(100*(int(r('lines-covered'))+int(r('branches-covered')))/(int(r('lines-valid'))+int(r('branches-valid')))))")
+          echo "### Coverage: $pct% (line + branch)" >> "$GITHUB_STEP_SUMMARY"
+      - name: SonarQube Cloud token present?
+        id: sonar
+        run: echo "token=${{ secrets.SONAR_TOKEN != '' }}" >> "$GITHUB_OUTPUT"
+      - name: SonarQube Cloud
+        if: steps.sonar.outputs.token == 'true'
+        uses: SonarSource/sonarqube-scan-action@e805d875275f728fac1885b413934be6d7c63f65 # v8.4.1
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      - name: SonarQube Cloud skipped
+        if: steps.sonar.outputs.token != 'true'
+        run: echo "::notice::SonarQube Cloud skipped - the SONAR_TOKEN secret is not set"
+
+  badge:
+    # The coverage badge: an SVG on the orphan branch `badges`, shown by the README as a repository file (works for a
+    # private repository, no external account).
+    needs: check
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: coverage
+      - name: Write badges/coverage.svg
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          pct=$(python3 -c "import xml.etree.ElementTree as E; r=E.parse('coverage.xml').getroot().get; print(int(100*(int(r('lines-covered'))+int(r('branches-covered')))/(int(r('lines-valid'))+int(r('branches-valid')))))")
+          color=$([ "$pct" -ge 90 ] && echo brightgreen || { [ "$pct" -ge 75 ] && echo yellow || echo red; })
+          curl -sSfL -o coverage.svg "https://img.shields.io/badge/coverage-${pct}%25-${color}"
+          git init -q badges && mv coverage.svg badges/ && cd badges
+          git config user.name "github-actions[bot]" && git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -q -b badges && git add coverage.svg && git commit -q -m "ci: coverage ${pct}%"
+          git push -qf "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" badges

steuermaschine-0.0.1/.github/workflows/codeql.yml

@@ -0,0 +1,22 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "17 4 * * 1"
+permissions:
+  contents: read
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: github/codeql-action/init@52cf1852265d99e9bea071b03366fc777a602909 # codeql-bundle-v2.27.4
+        with:
+          languages: python, actions
+      - uses: github/codeql-action/analyze@52cf1852265d99e9bea071b03366fc777a602909 # codeql-bundle-v2.27.4

steuermaschine-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.5"
+          python-version: "3.12"
+      - name: Install gitleaks
+        run: |
+          curl -sSfL -o gitleaks.tgz https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  gitleaks.tgz" | sha256sum -c -
+          tar -xzf gitleaks.tgz -C /usr/local/bin gitleaks && rm gitleaks.tgz
+      - name: The tag matches the package version
+        run: |
+          version=$(uv version --short --package steuermaschine)
+          [ "${GITHUB_REF_NAME}" = "v${version}" ] || { echo "::error::tag ${GITHUB_REF_NAME} != package version v${version}"; exit 1; }
+      - run: make install
+      - run: make check
+      - run: make build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: GitHub release with the built files
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes "See [CHANGELOG.md](CHANGELOG.md)." --verify-tag

steuermaschine-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+*.egg-info/
+.coverage
+.pytest_cache/
+.venv/
+__pycache__/
+coverage.xml
+dist/

steuermaschine-0.0.1/.gitleaks.toml

@@ -0,0 +1,7 @@
+# gitleaks defaults, plus recorded test fixtures whose "tokens" are digests and commit SHAs, not credentials.
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "recorded release freeze tokens (digests), branch->commit SHA maps, and a removed test's literal error text"
+paths = ['''^plugins/heinzel/tests/fixtures/(release|go)/''', '''^plugins/heinzel/tests/test_native_rehearse\.py$''']

steuermaschine-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+# Opt in: uvx pre-commit install --hook-type commit-msg --hook-type pre-commit
+repos:
+  - repo: local
+    hooks:
+      - id: commitizen
+        name: Conventional Commits (cz check)
+        entry: uv run cz check --allow-abort --commit-msg-file
+        language: system
+        stages: [commit-msg]
+      - id: ruff
+        name: ruff check
+        entry: uv run ruff check src examples tests
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: gitleaks
+        name: gitleaks (staged changes)
+        entry: gitleaks git --staged --redact --no-banner --pre-commit
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+      - id: confidentiality
+        name: private-term deny-list (files)
+        entry: uv run --script scripts/check_confidentiality.py
+        language: system
+        stages: [pre-commit]
+      - id: confidentiality-message
+        name: private-term deny-list (commit message)
+        entry: uv run --script scripts/check_confidentiality.py --identity --commit-msg
+        language: system
+        stages: [commit-msg]

steuermaschine-0.0.1/AGENTS.md

@@ -0,0 +1,113 @@
+# Agent instructions for this repository
+
+You work on `steuermaschine` (`sm`), a Typer CLI that steers changes from commit to live release. Read
+`docs/INTEGRATION.md` before your first change; it wins over your branch at merge. Binding goal:
+`docs/DEFINITION-OF-DONE.md`. Where a rule here blocks you, say so in your hand-over note; do not work around it.
+
+## Layout
+
+```
+src/steuermaschine/      core: generic, names no project, person, company or private path
+plugins/heinzel/         the large plugin: src/steuermaschine_heinzel/{plugin.py,toolmap.py,traps.py,native/,reviews/,parity/}, tests/
+examples/toy, layer/     small plugins; the toy is the quick start, the layer proves plugin stacking
+tests/                   core tests (tests/test_core_<module>.py), tests/projects, tests/gate_known.json
+docs/                    DESIGN, INTEGRATION (the contract), DEFINITION-OF-DONE, GAPS, NATIVE-PORT
+bin/                     check, promote, rollback, merge-slice, sm-dev, debt.py, gate_known.py
+```
+
+Native commands live in `native/<area>.py` (plus `native/<area>_lib/`), tests in
+`plugins/heinzel/tests/test_native_<area>*.py` with unique basenames repo-wide.
+
+## Hard rules (condensed from docs/INTEGRATION.md)
+
+- **Review units and digests.** A write command (`writes=True`) is off until `reviews/<path>.md` ends with
+  `VERDICT: APPROVE` for the exact digest of its unit (module plus its `*_lib`). `sm self reviews` shows unit,
+  digest, state. Never write the `REVIEWED:` or `VERDICT:` lines yourself.
+  The digest also covers every first-party file the unit imports, transitively (core and other `_lib` packages):
+  a change to core voids the verdicts of the units that import it. Every writer is under the gate: core's own
+  writers (`review verdict`, `focus add|done`, `alarm ack`, `ci cancel`), engine pipelines (`Pipeline(unit=...)`)
+  and every native command whose Changes line names a write (`sm self lint` flags a `writes=` that disagrees). The
+  only exception is `exempt="reason"`, honoured only for a path on the core's allowlist `native.EXEMPT_PATHS`
+  (`gate run`, the run lock every review's tests run through); any other `exempt=` is still gated.
+- **Reach the registry by name.** No module below `native/` or `pipelines/` imports `plugin.py` or `native/__init__.py`,
+  and a pipeline imports no command module: one such import puts the whole plugin into the unit's digest (23 commands had
+  202 to 225 files that way). Use `pipelines.common.command(path)` or `runtime().commands()`.
+  `plugins/heinzel/tests/test_native_digest_locality.py` fails on a wider digest; `steuermaschine.reviewgraph` shows what
+  a digest reaches and which verdicts a change voids.
+- **Pipelines compose, they do not reimplement.** `sm head admit` and `sm release cut` (plugin `pipelines/`) call
+  native commands through `native.call`, which applies that command's own gate; tests replace a step through
+  `pipelines.common.OVERRIDE`, never the gate.
+- **Never edit an approved unit without a new review.** Any change voids the verdict. A conflict in one goes back to
+  its owner.
+- **No wrappers.** No command starts an old script, and no `tools_dir` setting exists. A command exists only when it
+  is native; what is not ported shows as MISSING in `sm tools gaps`. Do not bring deleted files back.
+- **No real-path setting defaults.** No default may point at a real file or directory of a machine (no `~/...`, no
+  absolute path); a per-machine value defaults to `None` and the command that needs it refuses and names the key.
+  Every setting has a `description`; secrets are `SecretStr`.
+- **Tests are sandboxed.** The root `conftest.py` runs tests with HOME, XDG and state dirs in a temp directory and no
+  `SM_*`/`HZ_*`/`STEUERMASCHINE_*` variables. No network, no real `gh`, no sleep: use `fake_providers()`,
+  `FakeCommands`, `invoke(...)`. A test that writes a real file of the machine fails.
+- **Narrow interfaces.** Processes only through `providers.commands`, GitHub through `providers.forge`/`.ci` or
+  `steuermaschine.github.Gh`, time through `providers.clock`, state through `providers.store`, digests through
+  `steuermaschine.hashing.canonical_sha256`. No `subprocess`, `time.sleep`, `os.environ` or `fcntl` in native code.
+- **Never `git stash`.** The stash list is shared by all worktrees of the repository. Commit a WIP instead.
+- **One worktree per slice.** `git worktree add ../steuermaschine-wt-<slice> -b <branch> origin/main`; do not work in
+  the main checkout, which belongs to the integrator.
+- **Heavy runs go through the gate:** `sm gate run -- <command>` (full test suite, type checks, builds, pushes).
+  Focused tests may run directly.
+- **The core is clean and stays so:** ruff, mypy strict, pyright, 90% line+branch coverage, no dead code (vulture);
+  `bin/check` gates all of it. The plugin's typing, ruff and environment-read debt may only fall: `docs/debt.json`
+  is the ratchet (`uv run python bin/debt.py --record` in the commit that improves a number).
+- **Moved code stays verbatim.** Moved libraries and their moved tests keep their text so the diff against the
+  original is the review instrument; they get per-file ruff and mypy exceptions in `pyproject.toml`, and a verifier
+  (for example `plugins/heinzel/tests/packet_verbatim.py`) prints every changed line. Moved libraries expose functions only, no
+  `if __name__ == "__main__"`.
+- **Help and output.** Help in contract form via `H(...)`, every argument and option with its own `help=`;
+  `sm self lint` (strict) and `tests/test_core_help_order.py` must stay clean. Every command is `@native` and
+  returns a typed `Model` (core commands: `emit(..., Model)`); text through `render()`, JSON from the model
+  (`tests/test_core_json_contract.py` runs every command in json and parses it with its model). Errors
+  are `Refuse`/`Wait`, never `sys.exit`.
+- **Settings.** Typed only: a plugin field with a `description`, or `config.Environment` for a process variable.
+  Only `config.py` reads `os.environ` in the core; native modules read none (`tests/test_core_settings.py`).
+- **Privacy.** Never print, log or commit a configuration value that may be private (URLs, repository names, tokens,
+  paths). No old tool names (`hz-...`) in native output, help or state paths.
+
+## Run the tests and the gate
+
+```sh
+uv sync
+uv run pytest plugins/heinzel/tests/test_native_<area>.py     # focused
+sm gate run -- uv run pytest                                  # everything
+bin/check --fast      # tests, help lint per project, typos, ruff, mypy strict and pyright (core), vulture
+bin/check             # the same plus coverage >= 90 (core, plugin) and the plugin's debt ratchet (docs/debt.json)
+```
+
+## How a change reaches the live `sm`
+
+1. Build on a branch in your own worktree, small commits, tests green, rebased on `origin/main`.
+2. Hand over (branch, commit range, test count, files outside your area, settings added, what you could not verify;
+   see INTEGRATION.md section 7). The integrator merges with `bin/merge-slice BRANCH`, which refuses on red.
+3. Promotion: `bin/check`, then `bin/promote --check`, then `bin/promote`. It builds the committed HEAD into the
+   stable install and switches atomically; the coordinator decides when, never during a running admission or release.
+   It refuses while a gated write command is not approved at its digest: a change that moves a digest is not live
+   until that unit's new verdict is merged (`sm self reviews`).
+4. `bin/rollback` switches back to the previous release (run it again to go forward).
+
+## Commits
+
+Small, one area or command per commit; subject at most 72 characters. End every commit message with the trailer of
+the model that wrote it, for example:
+
+```
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
+```
+
+## Never
+
+- Push to `main`, or merge into it, without the integrator.
+- Edit the stable install (`~/Code/steuermaschine-stable` or whatever `SM_STABLE` names); it changes only through
+  `bin/promote` and `bin/rollback`.
+- Print configuration values, or put a private value in help, a test or a commit.
+- Edit an approved review unit, a `reviews/` verdict, or `tests/gate_known.json` by hand.
+- Run an old script, or add a wrapper around one.
+- Change repository settings, or open or merge a PR unless asked.

steuermaschine-0.0.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow [Semantic Versioning](https://semver.org).
+Entries are generated from [Conventional Commits](https://www.conventionalcommits.org) by
+[commitizen](https://commitizen-tools.github.io/commitizen/) (`make release`); edit wording by hand before tagging if needed.
+

steuermaschine-0.0.1/CLAUDE.md

@@ -0,0 +1 @@
+Read and follow AGENTS.md in this directory.

steuermaschine-0.0.1/Makefile

@@ -0,0 +1,46 @@
+# The single entry point for CI and release: standard tools only (uv, ruff, mypy, pyright, pytest, gitleaks, commitizen).
+.PHONY: install lint format typecheck test secrets audit build check release clean
+
+# The core with mypy's default rules; the codes below fail on today's code (debt: drop one when its findings are fixed).
+# The repository's [tool.mypy] (strict) stays the debt measure of bin/debt.py, so the gate ignores it.
+MYPY_DEBT := arg-type assignment attr-defined empty-body index operator union-attr var-annotated annotation-unchecked
+
+install:
+	uv sync --all-packages --locked
+
+# ruff format is not in the gate yet: most files predate it, and a mass reformat would collide with open branches.
+lint:
+	uv run ruff check src examples tests
+
+format:  # apply ruff format (not yet enforced; see lint)
+	uv run ruff format src examples tests
+
+typecheck:
+	uv run mypy --config-file= --python-version 3.12 $(MYPY_DEBT:%=--disable-error-code %) src/steuermaschine
+	uv run pyright
+
+# Coverage floor of the gate (line+branch, core+heinzel plugin, as CI measures it today); [tool.coverage] fail_under
+# = 90 stays the target that bin/check reports as debt.
+COV_FLOOR := 82
+
+# Typer forces colored help when GITHUB_ACTIONS, FORCE_COLOR or PY_COLORS is set; the help tests read plain text.
+test:
+	env -u GITHUB_ACTIONS -u FORCE_COLOR -u PY_COLORS uv run pytest --cov --cov-report=term --cov-report=xml --cov-fail-under=$(COV_FLOOR)
+
+secrets:
+	gitleaks git --redact --no-banner .
+	gitleaks dir --redact --no-banner .
+
+audit:
+	uv audit --locked --preview-features audit-command
+
+build:
+	rm -rf dist && uv build --package steuermaschine --out-dir dist
+
+check: lint typecheck test secrets
+
+release:  # bump from Conventional Commits, write CHANGELOG.md, commit, tag v*; then: git push --follow-tags
+	uv run cz bump --yes
+
+clean:
+	rm -rf dist .coverage coverage.xml .pytest_cache .mypy_cache .ruff_cache

steuermaschine-0.0.1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: steuermaschine
+Version: 0.0.1
+Summary: The artificial helmsman: a coordinator CLI that steers work from a change to a live release, for AI agents and a human owner.
+Requires-Python: >=3.12
+Requires-Dist: pluggy>=1.5
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# steuermaschine
+
+[![CI](https://github.com/helmut-hoffer-von-ankershoffen/steuermaschine/actions/workflows/ci.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/steuermaschine/actions/workflows/ci.yml)
+[![Coverage](https://github.com/helmut-hoffer-von-ankershoffen/steuermaschine/raw/badges/coverage.svg)](https://github.com/helmut-hoffer-von-ankershoffen/steuermaschine/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/steuermaschine/actions/workflows/codeql.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/steuermaschine/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/steuermaschine)](https://pypi.org/project/steuermaschine/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+<!-- SonarQube Cloud: the project is private, so its badges need a project badge token. Owner: SonarQube Cloud >
+     project > Information > Badges, copy the token, and replace BADGE_TOKEN below (all three). -->
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_steuermaschine&metric=alert_status&token=BADGE_TOKEN)](https://sonarcloud.io/summary/overall?id=helmut-hoffer-von-ankershoffen_steuermaschine)
+[![Security](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_steuermaschine&metric=security_rating&token=BADGE_TOKEN)](https://sonarcloud.io/summary/overall?id=helmut-hoffer-von-ankershoffen_steuermaschine)
+[![Reliability](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_steuermaschine&metric=reliability_rating&token=BADGE_TOKEN)](https://sonarcloud.io/summary/overall?id=helmut-hoffer-von-ankershoffen_steuermaschine)
+
+`sm` is a reusable coordinator that steers a change from commit to live release for projects in which AI agents do
+the work. It keeps resumable state per head (a commit on a work branch) and per release, always knows the one next
+command, and stops at review points where only the owner or an independent reviewer may continue. The core knows no
+project; pipelines, providers, gates and traps come from plugins (core plus plugins, wired with pluggy).
+
+The name: not a Steuermann or Steuerfrau, a human helmsman, but the artificial one: a Maschine that steers. The
+owner sets the destination and decides at the review stops.
+
+## Status
+
+Pre-release and private. Version 0.0.1. Every command is native; no command starts an old script
+(`sm tools gaps --wrapped` prints 0, `sm tools gaps` the rows not ported yet). The binding goal for the first
+release is [docs/DEFINITION-OF-DONE.md](docs/DEFINITION-OF-DONE.md). The plugin API (`steuermaschine.API_VERSION`)
+may still change.
+
+## Install
+
+From a clone, for now (PyPI later, project name `steuermaschine`):
+
+```sh
+git clone <repository-url> steuermaschine && cd steuermaschine
+uv tool install .          # puts `sm` and `steuermaschine` on your PATH
+```
+
+For development use `uv sync` and `bin/sm-dev` instead (see Development).
+
+## Quick start (toy plugin, no account needed)
+
+```sh
+uv sync && export PATH="$PWD/.venv/bin:$PATH"
+mkdir /tmp/toy && cd /tmp/toy && git init -q -b main && git commit -q --allow-empty -m init
+printf '[project]\nname = "toy-demo"\nplugin = "toy"\n' > steuermaschine.toml
+git checkout -q -b feat/hello && echo hi > hello.txt && git add hello.txt && git commit -q -m hello
+sm                         # PHASE idle
+sm head ship .             # dry run: stops before the first write outside this machine, prints what it would do
+sm head ship . --live      # pushes, opens the PR, then WAITING on CI
+sm sim ci green .          # play the outside world: CI turns green
+sm head ship . --live      # continues where it stopped: merge, tag, finished
+```
+
+Run the `uv sync` line in the clone, the rest in the scratch directory. The toy's forge and CI are a simulation in
+`.sim/world.json`; the engine, state, dry run, waiting and resuming are real. State lives under
+`~/.local/state/steuermaschine/<project>` (`STEUERMASCHINE_HOME` moves it).
+
+## The `go` contract
+
+Bare `sm` (same as `sm go`) is read-only and prints, in this order:
+
+- `PHASE`: where the project stands.
+- `NEXT`: the one command to type now.
+- `TRAP`: the mistake that is most likely at exactly this step. Read it before you run NEXT.
+
+`WAITING` appears when the run waits on the outside world (CI, a reviewer); run the same command again later.
+Exit codes: 0 done or a planned stop, 1 refused, 2 usage, 3 alarm, 70 tool error or plugin not loaded, 75 waiting.
+Every command has `--format json` with exactly one document and a published schema (`sm self schema`).
+
+## The review gate
+
+- A command that writes outside this machine, or changes state other commands act on, is a write command.
+- Write commands stay closed (exit 70, naming the review file) until an independent review approves them.
+- The approval names the exact digest of the reviewed code unit: the module, its `*_lib` package and every
+  first-party file it imports, transitively. Any edit to one of them voids it, also an edit to the core.
+- The reviewer is never the author: `sm review verdict DIGEST --approve --reviewer NAME` records it.
+- `sm self reviews` lists every write command, its unit, its digest and its state.
+
+- `bin/promote` refuses a build in which a gated write command is not approved: promoting it would switch that
+  command off.
+
+Writes that a pipeline step makes also need `--live`; without it a run stops with a dry-run plan. A pipeline
+(`sm head admit`, `sm release cut` in the Heinzelmännchen plugin) runs each step as a native command through that
+command's own gate, and stops at its review points until a different agent approved the digest.
+
+## Writing a plugin
+
+A plugin is an object (or module) with functions marked `@hookimpl`; the core calls the ones it implements:
+`sm_api_version`, `sm_settings`, `sm_pipelines`, `sm_gates`, `sm_traps`, providers such as `sm_forge` and `sm_ci`,
+`sm_native` (commands: `@native` functions that return a result model) and more. Every command follows the help
+contract (`sm self lint`, strict) and prints one typed JSON document with `--format json`. Register it as an
+entry point in group `steuermaschine.plugins` and name it in the project's
+`steuermaschine.toml` (`plugin = "..."`, or `plugins = ["base", "outer"]`; later entries are outer layers).
+`sm self hooks` lists the specifications, `sm self plugins` the loaded stack. Start from `examples/toy` (a complete
+plugin in one file), `examples/layer` (a second plugin layered on the first), `src/steuermaschine/hookspecs.py` and
+section 5 of [docs/DESIGN.md](docs/DESIGN.md). Test with `steuermaschine.testing` (`fake_providers`, `invoke`,
+conformance kit).
+
+## Development
+
+```sh
+uv sync                    # workspace: core, plugins/heinzel, examples/toy, examples/layer
+uv run pytest              # all tests, sandboxed (see docs/INTEGRATION.md section 8.5)
+bin/sm-dev ...             # run the development tree
+bin/check                  # the quality gate: tests, coverage >= 90, help lint, typos, ruff, mypy strict,
+                           # pyright, dead code, the plugin's debt ratchet (docs/debt.json); --fast skips coverage
+bin/promote --check        # everything a promote would test, without switching
+bin/promote                # build the committed HEAD into the stable install and switch to it
+bin/rollback               # switch the stable install back to the previous release (again: forward)
+```
+
+A stable install differs from the development tree: `sm` on the PATH runs a commit built with `git archive` into
+its own directory and virtual environment, non-editable, and nothing in it points at the checkout. Only
+`bin/promote` changes it, so editing or breaking the tree never breaks the live tool.
+
+## Docs
+
+- [docs/DESIGN.md](docs/DESIGN.md): purpose, pipelines as state machines, providers, plugins, help contract, output.
+- [docs/INTEGRATION.md](docs/INTEGRATION.md): the contract for every change handed to the integrator.
+- [docs/DEFINITION-OF-DONE.md](docs/DEFINITION-OF-DONE.md): the binding goal for the first release.
+- [docs/NATIVE-PORT.md](docs/NATIVE-PORT.md) and [docs/GAPS.md](docs/GAPS.md): how the old tools were ported.
+- [docs/RUNBOOK-release-cut.md](docs/RUNBOOK-release-cut.md): a release with `sm release cut`.
+- [docs/SWITCH-queue-daemon.md](docs/SWITCH-queue-daemon.md): switching the live queue daemon.
+- [AGENTS.md](AGENTS.md): instructions for coding agents working in this repository.