Auto-upgrade: daily workflow to propagate upstream changes to installed repos

[mrjf]

Problem

When autoloop's source workflows change (bug fixes, new features, breaking changes), installed copies in downstream repos become stale. There is no upgrade mechanism — the install is a one-time file copy + compile. This means fixes like #18, #20, #23, #25 don't reach repos like githubnext/tsessebe until someone manually re-copies and recompiles.

The tsessebe case demonstrates the cost: 18 duplicate PRs were created because the stale .lock.yml didn't include the reset-if-merged fix from PR #25.

Goal

A smooth, automated upgrade path that:

1. Detects upstream changes daily
2. Creates a PR in the downstream repo with the updated workflows
3. Handles breaking changes gracefully (adapts local customizations)
4. Requires minimal human intervention for non-breaking updates

Design

Component 1: upgrade-check agentic workflow (lives in autoloop repo, installed into downstream repos)

A new gh-aw agentic workflow that runs daily in the downstream repo:

on:
  schedule: daily
  workflow_dispatch:

What it does each run:

1. Detect upstream version: Fetch the latest autoloop source from githubnext/autoloop (using gh api or cloning to /tmp). Compare the upstream workflows/autoloop.md and workflows/sync-branches.md against the local .github/workflows/ copies.

2. Diff classification: Classify changes as:

   • Non-breaking: Documentation, prompt wording, new optional features, bug fixes that don't change the frontmatter schema. These can be applied automatically.
   • Breaking: Changes to frontmatter keys, step structure, tool configuration, permissions, or safe-output schema. These need agent-assisted adaptation.

3. Preserve local customizations: Before applying upstream changes, extract local overrides (e.g., schedule: every 30m instead of every 6h, custom network.allowed entries, modified safe-outputs limits). After applying upstream changes, re-apply local overrides.

4. Recompile: Run gh aw compile to regenerate .lock.yml files from the updated .md sources.

5. Validate: Run gh aw compile --validate to ensure the compiled output is valid.

6. Create PR: Open a draft PR with the changes titled [Autoloop] Upgrade workflows to <upstream-sha-short>. The PR body should include:

   • Changelog of upstream changes (commit messages since last upgrade)
   • Classification (breaking / non-breaking)
   • Any local customizations that were preserved
   • Any manual action required

Component 2: gh aw upgrade CLI command (lives in gh-aw)

A CLI counterpart for manual/interactive upgrades:

# Check for available updates
gh aw upgrade --check

# Apply upgrade, auto-fix breaking changes where possible
gh aw upgrade --fix

# Upgrade a specific workflow
gh aw upgrade autoloop --fix

--fix behavior:

• Detects the source repo from the .lock.yml header (Source: githubnext/autoloop)
• Fetches the latest upstream .md source
• Three-way merges: upstream base → upstream new → local, preserving local customizations
• Recompiles
• Reports what changed and what couldn't be auto-fixed

Component 3: Version tracking

Add a version/provenance block to the installed .md files so the upgrade tooling knows what baseline to diff against:

# Bottom of the installed .md file, or in a sidecar file
_autoloop:
  source: githubnext/autoloop
  installed_from: abc1234  # commit SHA at install time
  installed_at: 2026-04-04T05:00:00Z
  compiler_version: v0.65.6

Or a simpler approach: a .github/workflows/.autoloop-version.json:

{
  "source": "githubnext/autoloop",
  "commit": "abc1234def5678",
  "installed_at": "2026-04-04T05:00:00Z",
  "workflows": ["autoloop", "sync-branches"]
}

This gives the upgrade tooling a baseline commit to diff against, so it can show exactly what changed upstream since the last install/upgrade.

Implementation plan

Phase 1: Version tracking + gh aw upgrade CLI

1. Add version metadata to gh aw add — when installing, write .autoloop-version.json (or equivalent) recording the source commit.
2. Implement gh aw upgrade --check — compares installed commit against upstream HEAD, shows changelog.
3. Implement gh aw upgrade --fix — fetches upstream, three-way merges preserving local customizations, recompiles.

Phase 2: upgrade-check agentic workflow

1. Add workflows/upgrade-check.md to the autoloop repo.
2. Include it in the install process (add to install.md).
3. The workflow uses gh aw upgrade --fix internally, then creates a PR with the result.

Phase 3: Breaking change detection

1. Define a schema for the frontmatter DSL (what fields exist, what values are valid).
2. Classify upstream diffs against this schema to detect breaking vs non-breaking changes.
3. For breaking changes the agent can't auto-fix, create an issue instead of a PR, explaining what needs manual attention.

Open questions

• Should the upgrade workflow run as a gh-aw agentic workflow itself, or as a plain GitHub Actions workflow? An agentic workflow can reason about breaking changes and adapt, but a plain workflow is simpler and doesn't consume agent compute for routine updates.
• Should local customizations be extracted into a separate config file (e.g., .autoloop/config.yml) to make three-way merging cleaner? This would separate "upstream workflow logic" from "local overrides."
• How to handle the case where the user has made significant manual edits to the .md source beyond simple config overrides?