Basic versioning: VERSION file + self-check that opens an update-available issue on drift

Summary

Autoloop has no versioning today — no tags, no releases, no VERSION file. install.md clones main directly with no SHA pin, and gh aw add-wizard isn't a viable install path because the Autoloop install needs custom steps beyond what the wizard handles.

Result: installed copies of Autoloop drift silently from upstream. Users have no way to know they're behind, no way to see what changed, and no prompt to upgrade.

Propose a minimal versioning scheme: a plain version string in this repo, and a small self-check the installed Autoloop workflow runs on every execution. When the installed version doesn't match upstream, the workflow opens an issue in the consuming repo with a link to the diff. That's it — no CI tooling, no releases ceremony, no dependency on gh aw add.

Design

1. Plain VERSION file at the repo root

0.1.0

Bump it on any change to workflows/autoloop.md, workflows/sync-branches.md, workflows/shared/**, or .github/ISSUE_TEMPLATE/autoloop-program.md. Semver-ish, but don't over-engineer — even a monotonic integer would work. A human maintainer updates it when they merge a change they'd want consumers to notice. No automation needed.

Ship an adjacent CHANGELOG.md that lists what changed per version. Doesn't need to be exhaustive — one line per version is fine. The point is "if you're on 0.1.3 and upstream is 0.2.0, here's what happened between."

2. install.md records the installed version

Update install.md to copy VERSION into the consuming repo alongside the workflow files:

cp /tmp/autoloop/VERSION .github/autoloop-version

(Path is .github/autoloop-version rather than e.g. .autoloop/VERSION because .github/ is the natural home for meta-files about workflows in this repo, and keeping it out of .autoloop/ avoids conflating it with program definitions.)

3. Version check in the autoloop workflow pre-step

Add a step near the top of the autoloop workflow that:

1. Reads the locally installed version from .github/autoloop-version.
2. Fetches upstream's current VERSION from https://raw.githubusercontent.com/githubnext/autoloop/main/VERSION.
3. If they differ, checks whether an open "update available" issue already exists (dedupe by a stable title or label).
4. If no such issue exists, opens one with a link to the diff and the changelog.

Concrete implementation sketch:

  - name: Check for Autoloop upstream updates
    env:
      GITHUB_TOKEN: ${{ github.token }}
      GITHUB_REPOSITORY: ${{ github.repository }}
    run: |
      set -euo pipefail

      LOCAL_VERSION_FILE=".github/autoloop-version"
      UPSTREAM_URL="https://raw.githubusercontent.com/githubnext/autoloop/main/VERSION"

      if [ ! -f "$LOCAL_VERSION_FILE" ]; then
        echo "No local autoloop-version file; skipping drift check."
        exit 0
      fi

      LOCAL=$(tr -d '[:space:]' < "$LOCAL_VERSION_FILE")
      UPSTREAM=$(curl -fsSL "$UPSTREAM_URL" 2>/dev/null | tr -d '[:space:]' || echo "")

      if [ -z "$UPSTREAM" ] || [ "$LOCAL" = "$UPSTREAM" ]; then
        echo "Autoloop up to date (local=$LOCAL, upstream=$UPSTREAM)."
        exit 0
      fi

      echo "Autoloop is behind: local=$LOCAL, upstream=$UPSTREAM"

      # Dedupe: don't open a new issue if one is already open for this drift.
      EXISTING=$(gh issue list \
        --repo "$GITHUB_REPOSITORY" \
        --label "autoloop-update-available" \
        --state open \
        --search "in:title \"$UPSTREAM\"" \
        --json number \
        --jq '.[0].number // empty')

      if [ -n "$EXISTING" ]; then
        echo "Existing update-available issue #$EXISTING already open for $UPSTREAM."
        exit 0
      fi

      gh issue create \
        --repo "$GITHUB_REPOSITORY" \
        --title "[Autoloop] Update available: $LOCAL → $UPSTREAM" \
        --label "autoloop-update-available,automation,autoloop" \
        --body "$(cat <<EOF
      Your installed Autoloop is **$LOCAL**. Upstream is **$UPSTREAM**.

      - **Changelog**: https://github.com/githubnext/autoloop/blob/main/CHANGELOG.md
      - **Diff since your version**: https://github.com/githubnext/autoloop/compare/v$LOCAL...main

      To update, re-run the install steps in \`install.md\` from upstream, review the diff against your local \`.github/workflows/autoloop.md\` (you likely have local modifications), and bump \`.github/autoloop-version\` to \`$UPSTREAM\`.

      Close this issue when the update is complete — it will not re-open until the next version is published.
      EOF
      )"

4. Dedup / rate limit

• One open issue per distinct $UPSTREAM version. If upstream bumps again before a user closes the previous issue, the search would match the prior issue (different version in title), so a second issue opens for the newer version — that's fine.
• The user closes the issue when they complete the update and bump their local version file. Next scheduled run sees "local == upstream" and does nothing.
• Small amount of wasted API calls per run (one raw.githubusercontent.com fetch, one issue search) — trivial.

5. Graceful degradation

• No local version file → skip the check (first-run case for old installs that don't have the file).
• Upstream unreachable / network failure → skip without opening an issue; the next run will retry.
• Upstream version file missing → skip (means upstream hasn't shipped versioning yet, shouldn't alarm users).

What this is not

• Not automatic updates. Agents opening a PR to update the workflow is a bigger design decision (local modifications matter) and belongs in a separate issue.
• Not semver with compatibility guarantees. A monotonic version + changelog is enough for "notice drift."
• Not a replacement for gh aw add's SHA pinning. This is lighter-weight and works for installs that need custom steps (which the current Autoloop install does — it creates directories, writes templates, etc.).

Bootstrapping

To ship this, first add a VERSION file (0.1.0) and CHANGELOG.md to this repo, add the check step to workflows/autoloop.md, update install.md to copy VERSION, and add a small section to install.md explaining the .github/autoloop-version file. Existing users will naturally pick it up on their next re-install or when they manually copy in the new check step.

Acceptance

• VERSION file exists at repo root; CHANGELOG.md has at least one entry.
• install.md copies VERSION into .github/autoloop-version in the consuming repo.
• workflows/autoloop.md has a pre-step that compares local vs upstream and opens a single issue per detected drift.
• Duplicate-suppression works (running the workflow twice on stale version doesn't open two issues).
• The check fails gracefully when the network is unavailable.