loopcaptain 0.3.1__tar.gz

loopcaptain-0.3.1/.agent/AGENT_IMPROVEMENTS.md

@@ -0,0 +1,11 @@
+# Agent improvements
+
+Evidence-backed proposals for how work in this repository is done. An
+accepted one moves into its owner (AGENTS.md, a hook, a Makefile target)
+and its row is deleted; the commit says where it went.
+
+| # | Proposal | Evidence | Status |
+|---|---|---|---|
+| A2 | Run `ruff format` before string replacements in a file, or edit after formatting: the formatter rewraps lines and a replacement written against the old wrapping misses | Two replacement batches against `examples/demo_loop.py` failed on 2026-11-14 for this reason | open |
+| A3 | Headless Chrome cannot render narrower than 500 px, so a `--window-size=390` screenshot shows a clipped desktop layout, not a phone. Check a phone with device emulation over the DevTools protocol, and make that a `make phone` target that fails when a page is wider than 390 px | The clipped 390 px shots of 2026-11-15 were the 500 px minimum; emulation found the real overflows (600eca2) | open |
+| A4 | The shell here is bash 3.2: a command that mixes a heredoc with pipes or two heredocs is refused. Write a long commit message to a file and pass `-F <file>` | Several refused commits on 2026-11-15 | open |

loopcaptain-0.3.1/.agent/DEFERRED_VERIFICATION.md

@@ -0,0 +1,13 @@
+# Deferred verification
+
+Changes no real run has shown working yet. A row leaves when its evidence
+is named in the commit that closes it.
+
+| Commit | Change | Risk | Evidence that would close it |
+|---|---|---|---|
+| the MCP door | The MCP server ran over stdio against the SDK's own client (register, a round, a question, a refused call), not from a live agent session | An agent may use the tools differently than the docstrings intend, or skip calls | the server added as `loopcaptain mcp-config <agent>` prints, for two agents of different vendors, then one round reported from each session and seen on the board |
+| the protocol | The example loop and one loop a fresh agent built from the first prompt (2026-11-15, validate ok, doctor passed, on the board) have written it; no real loop with real costs and long reviews has | Fields real rounds need may be missing; long summaries may crowd the round table | One round of a real loop (F1) shown on the board |
+| the board | Looked at in Chrome, light and dark, at 1360 px, and at 390 px with device emulation (every page fits since 600eca2); not in Safari or Firefox, no keyboard-only pass, no automated accessibility run | Layout, focus or contrast faults outside Chrome | The pages opened in Safari and Firefox; a keyboard-only pass; a Lighthouse accessibility run |
+| ci/hardening | The workflows (three Pythons and macOS, security, scorecard, links, release, docs) passed zizmor, actionlint and the workflow schema; none has run on GitHub | A runner difference, a missing environment or a Pages setting fails the first run | The branch pushed, CI green on a pull request; the docs workflow publishing once |
+| the agents page | `docs/agents.md` follows a table read from each agent's documentation in the review of 2026-11-15; the entries for Gemini CLI, Cursor, opencode and Amp could not be confirmed in that review, and no line has been run | A wrong flag or file name sends a stranger the wrong way | The first prompt run in two agents of different vendors, each ending with a loop on the board |
+| fix/board-message-codes | A loop page shows the green or red message only with a seal from this server process; tested through the app, not looked at on a running board | A message after a reply, stop or start no longer shows | `make demo`, `make serve`, press Stop on the example loop: the message shows; the same address with `note=` changed shows none |

loopcaptain-0.3.1/.agent/FINDINGS.md

@@ -0,0 +1,17 @@
+# Findings
+
+Observations outside the task at hand. A row is recorded, a person
+decides; a picked row moves to `docs/BACKLOG.md`, a settled one is deleted
+in the commit that settles it. Proposed: now, later, check, drop.
+
+| # | Finding | Status | Proposed | Evidence |
+|---|---|---|---|---|
+| F1 | The five loops this was designed around do not write `.loops/` yet. Each maps cleanly: (a) the two brief-and-lenses loops: BRIEF front matter -> `loop.json` (lenses -> review steps, `rounds` -> `round_cap`), `.rounds/N/plan.md` -> `round_started`, `lens-*.md` with its MATERIAL GAPS count -> `step_finished` findings, `cost.md` rows -> `cost`, `gate.md`, `verdict.md` and the thread entry -> `round_finished`, "Needs you" -> `question`, the thread's reply slot -> inbox; (b) the three research loops: `brief/brief.md` -> brief, `policy.py` reviewers and models -> steps, `work/rounds/N-worklist.yaml` -> `round_started`, `N-review-*.md` -> findings, `N-gate.md`, `N-verdict.md` -> `round_finished`, the approval file -> `question` | open | now, one loop first | the loops' round folders, read 2026-11-14 |
+| F2 | The repository's home and name are not final. The connect sentence in `README.md` and `standard/AGENTS.md` says "the Loopcaptain repository" without an address, and the README has no CI badge | open | now, once the home is decided | README.md, standard/AGENTS.md |
+| F5 | Protocol proposal: an optional `fingerprint` per finding (the helper computes it) so the board can follow one finding across rounds and show "open since round N"; replaces the rule that reviews are fresh each round where a loop sends it | open | later: the first thing after real loops are connected | published practice on review and gates, read 2026-11-14; docs/ARCHITECTURE.md section 7 |
+| F7 | Protocol proposals to leave out of version 1: control role separate from activity, four severities with a separate blocking flag, lens criteria with ids, the gate declared as data, `done_when` checks, run ids, trigger, autonomy levels, SARIF export, a `by` on a closed finding. Each adds vocabulary a loop author must learn; unknown fields are allowed, so a loop can already carry them | open | drop for version 1, revisit with F5 | published loop tooling, read 2026-11-14; docs/ARCHITECTURE.md section 14 |
+| F9 | A notification bridge (a phone message when a loop asks, a reply that lands in `inbox.jsonl`) would need an outside service and a rule for who may write the inbox | open | later | published human-in-the-loop tooling, read 2026-11-14 |
+| F15 | An optional exporter that tails `events.jsonl` and sends OTLP along docs/opentelemetry.md: its own process and dependency group, off by default, the first thing that would send data off the machine | open | later: when someone wants loops beside agent traces | docs/ARCHITECTURE.md section 15 |
+| F17 | The tab title counts what waits; the favicon does not. A count in the icon needs a drawn image per number or script | open | later | src/loopcaptain/board/templates/overview.html |
+| F18 | A prompt to build a loop, given to a fresh agent, ended with a 302-line loop file for a three-step job; a smaller starting template (one loop.py of 60 lines beside the helper) would make the first loop cheaper | open | later: check with the next acceptance run | the acceptance run of 2026-11-15 |
+| F19 | "Door" is used for the two ways a loop writes its files (the MCP server's docstring and so `docs/reference/mcp.md`, `mcp_server/AGENTS.md`, `standard/LOOPS.md` section 5). A reader new to the project does not know what a door is; the architecture heading and picture now say "ways in" and name the script and MCP | open | later: reword with the next change to those files, then `make docs-pages` | `git grep -n -i door`, 2026-11-15 |

loopcaptain-0.3.1/.agent/UPSTREAM_ISSUES.md

@@ -0,0 +1,8 @@
+# Upstream issues
+
+Behaviour of external tools this repository works around. Filing upstream
+is a public post and needs the person's yes.
+
+| # | Upstream | Behaviour | Workaround | Report |
+|---|---|---|---|---|
+| U1 | `mcp` Python SDK 2.x | `FastMCP` was renamed to `MCPServer` (`mcp.server.mcpserver`); code written for 1.x fails on import | `pyproject.toml` requires `mcp>=2.0` and `mcp_server/server.py` imports `MCPServer` | none needed: documented in the SDK's migration guide |

loopcaptain-0.3.1/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.{md,tex}]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false

loopcaptain-0.3.1/.env.example

@@ -0,0 +1,16 @@
+# Both are optional. The board runs without a .env file.
+
+# Path of the config that lists the watched repositories.
+# Default: loopcaptain.local.yaml in the folder the board is started in.
+LOOPCAPTAIN_CONFIG=
+
+# Folder for the pid records and logs of loops the board started.
+# Default: .state in the folder the board is started in.
+LOOPCAPTAIN_STATE=
+
+# Folders, separated by ":", under which the MCP tools may write besides the
+# folder the server was started in.
+LOOPCAPTAIN_MCP_ROOTS=
+
+# The key the board signs inbox lines with. Default: ~/.config/loopcaptain/inbox.key
+LOOPCAPTAIN_INBOX_KEY=

loopcaptain-0.3.1/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change is reviewed by the maintainer.
+* @danielvogler

loopcaptain-0.3.1/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,26 @@
+name: Something is wrong
+description: The board, the command line or the MCP server does not do what it should.
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what you expected
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to see it
+      description: The commands, the page, and a few lines of the loop's files if they matter. Invent the content; never paste a real loop's text.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "`loopcaptain --version` or the commit"
+  - type: input
+    id: system
+    attributes:
+      label: System and browser

loopcaptain-0.3.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: A security problem
+    url: https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability
+    about: Report it privately through this repository's security advisories, not as an issue.

loopcaptain-0.3.1/.github/ISSUE_TEMPLATE/loop-not-showing.yml

@@ -0,0 +1,23 @@
+name: A loop does not show up
+description: A loop writes .loops/ but the board does not show it, or shows it wrong.
+labels: [connect]
+body:
+  - type: textarea
+    id: validate
+    attributes:
+      label: What `loopcaptain validate <repository>` prints
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: How the board watches the repository
+      description: The roots and repos entries, with your own folder names replaced.
+      render: yaml
+  - type: textarea
+    id: what
+    attributes:
+      label: What you expected to see
+    validations:
+      required: true

loopcaptain-0.3.1/.github/ISSUE_TEMPLATE/protocol.yml

@@ -0,0 +1,25 @@
+name: A protocol proposal
+description: A field or an event the Loops protocol lacks.
+labels: [protocol]
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: What a real loop could not say
+      description: The loop, in invented words, and what it had to do instead.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: The field or event, as a line of events.jsonl
+      render: json
+    validations:
+      required: true
+  - type: checkboxes
+    id: grows
+    attributes:
+      label: Protocol 1 only grows
+      options:
+        - label: The proposal is optional; a loop written against today's text still validates.
+          required: true

loopcaptain-0.3.1/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+      semver-major-days: 14
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+      semver-major-days: 14
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: pre-commit
+    directory: /
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+      semver-major-days: 14
+    groups:
+      hooks:
+        patterns: ["*"]

loopcaptain-0.3.1/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+<!-- The title is a commit subject: type(scope): subject. Write about the change, never about the
+     conversation that led to it: no "as requested", no "the user wants". AGENTS.md has the rules. -->
+
+## What changes for a user
+
+<!-- One or two sentences. The subjects of the feat, fix and perf commits become the release notes. -->
+
+## Why
+
+<!-- The problem, with evidence: an issue, a finding, a run. -->
+
+## Done when
+
+- [ ] A test fails without this change, and `make check` is green.
+- [ ] Looked at for real (`make demo`, `make serve`), or listed in `.agent/DEFERRED_VERIFICATION.md`.
+- [ ] Text, models and schema of the standard agree (`make schema`), if the protocol changed.
+- [ ] `feat`, `fix` and `perf` subjects read as lines of release notes; a decision has its section in `docs/ARCHITECTURE.md`.
+- [ ] Nothing names a company, a client or a real loop.
+- [ ] The title and this text describe the change, not the conversation that led to it.

loopcaptain-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Actions are pinned to commits, not tags: a tag can be moved onto other code.
+# The comment names the release for the human reading it.
+jobs:
+  check:
+    name: make check (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.12", "3.13", "3.14"]
+        include:
+          # The board starts processes and reads process groups: check it where people run it.
+          - os: macos-latest
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: uv sync --frozen
+
+      # No model and no network: the tests run the example loop, which calls no agent.
+      - name: Check
+        run: make check
+        env:
+          UV_NO_SYNC: "1"
+
+  secrets:
+    name: gitleaks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0  # a secret committed once and reverted is still leaked
+          persist-credentials: false
+
+      # The gitleaks CLI directly, pinned by digest: the same release as the pre-commit hook.
+      - name: Scan history for secrets
+        run: >-
+          docker run --rm -v "$PWD:/repo"
+          ghcr.io/gitleaks/gitleaks:v8.30.1@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f
+          git /repo --redact --verbose --exit-code 1

loopcaptain-0.3.1/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: docs
+
+# Builds the documentation site on every change to main, and publishes it to GitHub Pages with
+# the official flow only when the repository variable PUBLISH_DOCS is "true". A Pages site is
+# public even when the repository is private, so publishing waits for the decision to go public.
+# Only the deploy job may write to Pages or mint an identity token, in the `github-pages`
+# environment. No versioned docs before 1.0.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          uv sync --frozen
+          uv run --group docs zensical build --clean
+          cp docs/llms.txt site/llms.txt
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    if: vars.PUBLISH_DOCS == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

loopcaptain-0.3.1/.github/workflows/links.yml

@@ -0,0 +1,28 @@
+name: links
+
+# Weekly: do the links in the documents still lead somewhere? Never a gate: a site that is down
+# for an hour must not block a change. A failure opens nothing; read the run.
+
+on:
+  schedule:
+    - cron: "41 6 * * 1"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
+        with:
+          args: >-
+            --no-progress --max-retries 3
+            --exclude '^https?://127\.0\.0\.1'
+            './**/*.md'
+          fail: true

loopcaptain-0.3.1/.github/workflows/pr-description.yml

@@ -0,0 +1,62 @@
+name: pr-description
+
+# The commit-msg hooks keep AI attribution and conversation out of commits and hold the subject
+# to Conventional Commits, but nothing local ever sees a pull request's title or description.
+# This runs the same hooks on both, so each pattern lives in one place
+# (.pre-commit-config.yaml). Separate from ci.yml so editing a description re-runs
+# only this, not the whole gate.
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions: {}
+
+jobs:
+  attribution:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.12'
+
+      # Through env, never interpolated into the script: the description is untrusted text.
+      - name: Write the PR description to a file
+        env:
+          BODY: ${{ github.event.pull_request.body }}
+        run: printf '%s\n' "$BODY" > "$RUNNER_TEMP/pr-description.txt"
+
+      - name: Reject AI attribution in the PR description
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+        with:
+          extra_args: >-
+            no-agent-coauthors --hook-stage commit-msg
+            --commit-msg-filename ${{ runner.temp }}/pr-description.txt
+
+      # The description is about the change, never about the conversation that led to it
+      # (AGENTS.md, "Commits and pull requests").
+      - name: Reject conversation in the PR description
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+        with:
+          extra_args: >-
+            no-conversation --hook-stage commit-msg
+            --commit-msg-filename ${{ runner.temp }}/pr-description.txt
+
+      # The title becomes a line of the changelog when a pull request is squashed.
+      - name: Write the PR title to a file
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: printf '%s\n' "$TITLE" > "$RUNNER_TEMP/pr-title.txt"
+
+      - name: The PR title is a Conventional Commit subject
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+        with:
+          extra_args: >-
+            conventional-commit --hook-stage commit-msg
+            --commit-msg-filename ${{ runner.temp }}/pr-title.txt

loopcaptain-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,108 @@
+name: release
+
+# Every push to main that brings a feat, fix or perf commit gets the next version as a tag and a
+# GitHub release, with those commits as its notes and the built wheel attached
+# (scripts/release.py, docs/ARCHITECTURE.md section 19). Nothing is committed back, so nobody
+# bumps a version, pushes a tag or opens a pull request for one. The wheel is stamped with the
+# tag's version in the runner, proved to work installed outside a checkout, and published to PyPI
+# by trusted publishing (no token stored anywhere) once the repository variable PUBLISH_PYPI is
+# "true".
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+# One release at a time, in push order, so two merges never take the same tag.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: tag and release
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write  # the tag and the release
+    outputs:
+      tag: ${{ steps.next.outputs.tag }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0  # every tag and the commits since the last one
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.12"
+
+      - name: Next version
+        id: next
+        run: echo "tag=$(uv run --no-project python scripts/release.py --notes "$RUNNER_TEMP/release-notes.md")" >> "$GITHUB_OUTPUT"
+
+      - name: Stamp the version and build
+        if: steps.next.outputs.tag != ''
+        env:
+          TAG: ${{ steps.next.outputs.tag }}
+        run: |
+          uv version "${TAG#v}"
+          uv build
+
+      - name: Install the wheel in a clean environment and use it
+        if: steps.next.outputs.tag != ''
+        env:
+          TAG: ${{ steps.next.outputs.tag }}
+        run: |
+          uv venv /tmp/clean
+          uv pip install --python /tmp/clean/bin/python dist/*.whl
+          cd /tmp
+          test "$(/tmp/clean/bin/loopcaptain --version)" = "loopcaptain ${TAG#v}"
+          /tmp/clean/bin/loopcaptain spec > /dev/null
+          /tmp/clean/bin/loopcaptain demo --target /tmp/demo --no-watch
+          /tmp/clean/bin/loopcaptain validate --strict /tmp/demo
+
+      - name: Tag and release
+        if: steps.next.outputs.tag != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ steps.next.outputs.tag }}
+        run: >-
+          gh release create "$TAG" dist/*.whl dist/*.tar.gz --target "$GITHUB_SHA" --title "$TAG"
+          --notes-file "$RUNNER_TEMP/release-notes.md"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: steps.next.outputs.tag != ''
+        with:
+          name: dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    needs: release
+    if: needs.release.outputs.tag != '' && vars.PUBLISH_PYPI == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write       # trusted publishing to PyPI
+      attestations: write   # build provenance
+      contents: read
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: dist/*
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+
+      - name: Publish
+        run: uv publish --trusted-publishing always dist/*

loopcaptain-0.3.1/.github/workflows/scorecard.yml

@@ -0,0 +1,35 @@
+name: scorecard
+
+# The OpenSSF Scorecard, weekly: how the repository's own practices look to a stranger who has
+# to decide whether to trust it. Results go to the code scanning tab, never block a change.
+
+on:
+  schedule:
+    - cron: "17 5 * * 1"
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  analysis:
+    # The Scorecard reads a repository as a stranger would, so it runs only once it is public.
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      id-token: write  # publishes the result to the OpenSSF API
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
+        with:
+          sarif_file: results.sarif

loopcaptain-0.3.1/.github/workflows/security.yml

@@ -0,0 +1,37 @@
+name: security
+
+# What the code review of a workflow and a dependency cannot see by eye: zizmor reads every
+# workflow for injection and credential leaks; dependency review refuses a pull request that adds
+# a dependency with a known vulnerability. CodeQL runs by GitHub's default setup, a repository
+# setting, not a workflow.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: zizmorcore/zizmor-action@45d7276c9ca790aabd705e31ca99c6185c3e76dd # v0.8.1
+        with:
+          advanced-security: false
+
+  dependencies:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        with:
+          fail-on-severity: moderate

loopcaptain-0.3.1/.gitignore

@@ -0,0 +1,23 @@
+# Finder and editor clutter
+.DS_Store
+/.serena/
+
+# Environments, caches, coverage
+/.venv/
+__pycache__/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/
+/.coverage
+/site/
+
+# Secrets
+/.env
+
+# Which repositories this laptop's board watches, the demo loop's working
+# folder, and the logs of processes the board started
+*.local
+*.local.md
+*.local.yaml
+/demo/
+/.state/