Dependency Release Monitor Loop

The dependency-release-monitor loop watches upstream releases and changelogs for a declared dependency list, compares each latest release against the version a project says it uses, and writes an impact report with an explicit act or ignore recommendation, confidence, risk, evidence, and approval status.

This directory is a draft template. "Draft" is registry/site operational metadata for the template directory, not a hidden loop.yaml field; the manifest itself uses only the fields defined by spec/loop-spec-v0.1.md.

Files

• loop.yaml — agent-readable manifest for the template.
• AGENT-INSTALL.md — exact install commands for cron, GitHub Actions, and agent-kanban backends.
• scripts/dependency_release_monitor.py — concrete standard-library runner used by all backends.
• examples/dependencies.json — editable dependency list for real runs.
• examples/dry-run-dependencies.json — local-only dependency list used by verification.
• examples/sample-release-feed.json and examples/sample-ui-kit-feed.json — deterministic local release feeds used by the dry run.
• examples/github-actions/dependency-release-monitor.yml — ready-to-copy workflow.
• verification/expected-output.md — expected dry-run output and interpretation.
• verification/dry-read-ambiguity-checklist.md — dry-read checklist for this revision.

The seven human questions

1. What loop do I need?

Use this loop when a project needs recurring awareness of dependency, library, framework, or GitHub Action releases and the desired output is a cited impact report rather than an automatic dependency bump. It matches the watchdog plus judgment pattern in docs/research/loop-landscape.md §6.5 and the LM-TPL-05 plan.

2. What can it safely automate?

The manifest permits reading configured web/repo/file release sources, reading the declared dependency config, writing a report, writing duplicate-suppression state, creating a proposal branch, and creating follow-up tasks. It forbids merging dependency changes, changing credentials, public publishing, spending money, deleting user data, and mutating upstream projects without approval. These claims map to permissions.allowed_actions and permissions.forbidden_actions in loop.yaml.

3. What do I need to connect?

Minimum setup needs this repository, Python 3, a JSON dependency list, release sources for each dependency, an output directory, and a state path. The checked-in runner supports file, url, rss, and github_releases release sources. GitHub Actions PR mode also needs the built-in GITHUB_TOKEN permissions declared in the workflow. Agent-kanban mode needs a configured task board or Hermes kanban installation.

No extra credential is required by the default template. If a private registry, private repository, or authenticated changelog is added later, update the dependency config, loop.yaml inputs.environment_variables/permissions.credential_scopes, and the selected backend secret store in the same change.

4. What can go wrong?

Release feeds can be unavailable, tags can be non-semver, changelogs can omit migration risk, prereleases can look newer than stable releases, and a weak signal can cause unnecessary update work. The runner records fetch/parse errors in the report, lowers confidence when versions do not parse, ignores prereleases by default per dependency config, raises risk for major jumps and security/breaking/migration keywords, and gates major upgrades, low-confidence recommendations, credential changes, and dependency merges.

5. How do I know it worked?

A successful run prints DEPENDENCY_RELEASE_REPORT=..., DEPENDENCY_RELEASE_STATE=..., DEPENDENCIES_CHECKED=..., NEW_RELEASES=..., RECOMMEND_ACT=..., and FETCH_ERRORS=.... The report must contain the five Loopmaster self-maintenance sections: what changed, evidence/source links, recommended action, confidence+risk, and autonomy/approval status. The exact verification commands are in loop.yaml under verification.commands, in AGENT-INSTALL.md, and in verification/expected-output.md.

6. How do I stop or roll it back?

For cron, remove the dependency_release_monitor.py line from the user's crontab. For GitHub Actions, disable or delete .github/workflows/dependency-release-monitor.yml. For agent-kanban, pause or remove the recurring task. Rollback is intentionally narrow: leave the previous state file unchanged when report generation fails; if a bad report PR is opened, close the PR or revert that report commit. This maps to failure_policy.rollback.

7. What should I improve after the first run?

Review the dependency list, assign criticality honestly, add watch keywords for project-specific risks, prune noisy release sources, tune cadence, and decide which act recommendations should create kanban cards. Record maintenance evidence in the audit log path declared by maintenance.audit_log; the template's freshness cadence is weekly.

Backend behavior

All supported backends run the same helper and the same manifest validation command. Backend differences are installation and delivery only:

• cron writes reports and state on the machine where cron runs.
• github_actions writes reports/state on a branch and opens a pull request using peter-evans/create-pull-request.
• agent_kanban creates a recurring agent task whose prompt runs the helper, reviews act recommendations, and creates follow-up cards for high-risk or low-confidence releases.

The template reports dependency-release recommendations only. It does not edit lockfiles, package manifests, or workflow pins; that work should happen in a separate dependency-update task with project-specific tests.

Dependency config shape

examples/dependencies.json uses this shape:

{
  "dependencies": [
    {
      "name": "astro",
      "ecosystem": "npm",
      "current_version": "5.0.0",
      "used_for": "static site build",
      "criticality": "medium",
      "ignore_prereleases": true,
      "watch_keywords": ["security", "breaking", "migration"],
      "release_source": {"type": "github_releases", "url": "https://github.com/withastro/astro"}
    }
  ]
}

Supported release_source.type values in the checked-in runner:

• file — deterministic local JSON with a top-level releases array; used for dry-run verification.
• github_releases — GitHub repository URL converted to the public releases API.
• rss — RSS or Atom feed.
• url — JSON release array/object or an HTML changelog page.

Confidence and risk handling

• Confidence is high when both current and latest versions parse as semver-like versions.
• Confidence drops when the release source is ambiguous, missing, or non-semver.
• Risk is raised by major-version jumps, security/breaking/migration/deprecation keywords, and high-criticality dependencies.
• act means a human or follow-up agent should review/update through the normal dependency workflow; it does not mean this loop may merge the update.
• ignore means no action is recommended for this run because no newer stable release was found, the current version already matches the latest readable release, or the finding is below the action threshold.

Agent install guide — Dependency Release Monitor Loop

Run commands from the repository root unless a step says otherwise. Replace paths only when your target repo intentionally uses different report/state locations.

0. Preflight

python3 --version
python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py --help
uv run --with check-jsonschema --with pyyaml check-jsonschema \
  --schemafile spec/loop.schema.json \
  templates/dependency-release-monitor/loop.yaml

Expected output:

Python 3.x.x
usage: dependency_release_monitor.py ...
ok -- validation done

Failure branches:

• python3: command not found — install Python 3 or use a backend image that includes it.
• No such file or directory — confirm you are at repo root and that templates/dependency-release-monitor/ exists.
• schema validation failure — fix loop.yaml before installing any backend.

1. Verify the concrete runner locally

rm -rf /tmp/loopmaster-dependency-release-monitor /tmp/loopmaster-dependency-release-monitor-state.json
python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py \
  --dependencies templates/dependency-release-monitor/examples/dry-run-dependencies.json \
  --state /tmp/loopmaster-dependency-release-monitor-state.json \
  --output-dir /tmp/loopmaster-dependency-release-monitor \
  --max-releases 5

Expected output shape on a fresh state file:

DEPENDENCY_RELEASE_REPORT=/tmp/loopmaster-dependency-release-monitor/YYYY-MM-DD-dependency-release-monitor.md
DEPENDENCY_RELEASE_STATE=/tmp/loopmaster-dependency-release-monitor-state.json
DEPENDENCIES_CHECKED=2
NEW_RELEASES=2
RECOMMEND_ACT=1
FETCH_ERRORS=0

Then verify duplicate suppression:

python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py \
  --dependencies templates/dependency-release-monitor/examples/dry-run-dependencies.json \
  --state /tmp/loopmaster-dependency-release-monitor-state.json \
  --output-dir /tmp/loopmaster-dependency-release-monitor \
  --max-releases 5

Expected output: NEW_RELEASES=0, RECOMMEND_ACT=0, and FETCH_ERRORS=0.

Failure branches:

• FETCH_ERRORS is non-zero on the dry run — a local sample feed is unreadable or invalid; fix the path in examples/dry-run-dependencies.json.
• RECOMMEND_ACT is not 1 on fresh state — inspect examples/sample-release-feed.json; the sample must include example-agent-sdk 2.0.0 with breaking/security language.
• report is missing confidence/risk — inspect the generated Markdown and fix the runner before scheduling.

2. Configure dependencies

Edit a project-local copy of templates/dependency-release-monitor/examples/dependencies.json. Keep the top-level shape:

{
  "dependencies": [
    {
      "name": "astro",
      "ecosystem": "npm",
      "current_version": "5.0.0",
      "used_for": "static site build",
      "criticality": "medium",
      "ignore_prereleases": true,
      "watch_keywords": ["security", "breaking", "migration"],
      "release_source": {"type": "github_releases", "url": "https://github.com/withastro/astro"}
    }
  ]
}

Supported by the checked-in runner: file, url, rss, and github_releases.

No private registry or private-repository credential exists by default. If no credential exists, use only public release sources and do not add an env var or credential scope to loop.yaml. If you later add a private release source, persist its secret in the backend secret store and update the manifest and runtime dependency file in the same PR. A one-time export TOKEN=... is not a valid cron install because cron does not inherit that interactive shell.

3. Backend A — cron

Cron runs on one machine and writes reports/state into that checkout. It does not open a PR by itself and it does not edit dependency files.

Create a persistent environment file, even if it currently contains no secrets:

mkdir -p .loopmaster/state .loopmaster/env docs/dependencies
cat > .loopmaster/env/dependency-release-monitor.env <<'EOF'
# Optional secrets go here as KEY=value lines.
# Do not commit this file.
DEPENDENCY_RELEASE_CONFIG=templates/dependency-release-monitor/examples/dependencies.json
DEPENDENCY_RELEASE_STATE=.loopmaster/state/dependency-release-monitor.json
DEPENDENCY_RELEASE_OUTPUT_DIR=docs/dependencies
EOF
chmod 600 .loopmaster/env/dependency-release-monitor.env
printf '\n.loopmaster/env/*.env\n' >> .git/info/exclude

Install the cron entry:

REPO_ROOT=$(pwd)
CRON_LINE="0 10 * * 1 cd $REPO_ROOT && set -a && . ./.loopmaster/env/dependency-release-monitor.env && set +a && /usr/bin/env python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py --dependencies \"\$DEPENDENCY_RELEASE_CONFIG\" --state \"\$DEPENDENCY_RELEASE_STATE\" --output-dir \"\$DEPENDENCY_RELEASE_OUTPUT_DIR\" >> .loopmaster/state/dependency-release-monitor.cron.log 2>&1"
( crontab -l 2>/dev/null | grep -v 'templates/dependency-release-monitor/scripts/dependency_release_monitor.py' ; printf '%s\n' "$CRON_LINE" ) | crontab -
crontab -l | grep 'dependency_release_monitor.py'

Expected output: one crontab line containing templates/dependency-release-monitor/scripts/dependency_release_monitor.py.

Test the exact command outside cron:

set -a && . ./.loopmaster/env/dependency-release-monitor.env && set +a
python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py \
  --dependencies "$DEPENDENCY_RELEASE_CONFIG" \
  --state "$DEPENDENCY_RELEASE_STATE" \
  --output-dir "$DEPENDENCY_RELEASE_OUTPUT_DIR"

Expected output: DEPENDENCY_RELEASE_REPORT=docs/dependencies/..., DEPENDENCY_RELEASE_STATE=.loopmaster/state/dependency-release-monitor.json, and counts.

Failure branches:

• crontab: command not found — this backend is unavailable; use GitHub Actions or agent-kanban.
• cron log shows missing env vars — check .loopmaster/env/dependency-release-monitor.env permissions and the set -a && . ... segment.
• private source secrets are needed — add KEY=value to .loopmaster/env/dependency-release-monitor.env only; never commit it and never rely on a one-time interactive export.
• FETCH_ERRORS is non-zero — inspect .loopmaster/state/dependency-release-monitor.cron.log and the generated report; fix sources or network access before treating the run as verified.

Stop cron:

crontab -l | grep -v 'templates/dependency-release-monitor/scripts/dependency_release_monitor.py' | crontab -

4. Backend B — GitHub Actions

GitHub Actions runs weekly or manually, writes a report/state update, and opens a PR. It uses repository permissions, not local cron secrets. It does not update dependency files.

Install the workflow:

mkdir -p .github/workflows .loopmaster/state docs/dependencies
cp templates/dependency-release-monitor/examples/github-actions/dependency-release-monitor.yml .github/workflows/dependency-release-monitor.yml
git add .github/workflows/dependency-release-monitor.yml templates/dependency-release-monitor/examples/dependencies.json
git diff --cached -- .github/workflows/dependency-release-monitor.yml

Expected output: a workflow containing:

permissions:
  contents: write
  pull-requests: write

Commit and push the workflow in the normal PR flow. After merge, run it manually:

gh workflow run dependency-release-monitor.yml
sleep 10
gh run list --workflow dependency-release-monitor.yml --limit 1

Expected output shape:

STATUS  TITLE  WORKFLOW  BRANCH  EVENT  ID  ELAPSED  AGE

When the run succeeds, expected result is a new PR titled docs(deps): add dependency release monitor report if the runner changed docs/dependencies/*.md or .loopmaster/state/dependency-release-monitor.json. If there are no changes because state already contains all latest releases, peter-evans/create-pull-request completes without opening a duplicate PR.

Failure branches:

• gh: command not found or unauthenticated — use the GitHub web UI to run the workflow, or authenticate gh.
• workflow fails at checkout or permission step — confirm repo Actions permissions allow contents: write and pull-requests: write.
• workflow fails in Run dependency release monitor — inspect the run log; fix examples/dependencies.json or network assumptions.
• private release source added without secret — remove the private source and matching manifest credential fields, or add the provider secret under GitHub repository Settings → Secrets and variables → Actions and reference it in the workflow env: block.

Disable GitHub Actions backend:

git rm .github/workflows/dependency-release-monitor.yml
git commit -m "chore: disable dependency release monitor workflow"

5. Backend C — agent-kanban

Agent-kanban assigns a recurring task to an agent. The task must still run the concrete helper and record evidence; it is not a prose-only reminder.

For Hermes kanban, create a recurring scheduler job or board task whose prompt is self-contained. Example prompt:

Run the Loopmaster dependency-release-monitor loop from repo root. Commands:
1. uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json templates/dependency-release-monitor/loop.yaml
2. python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py --dependencies templates/dependency-release-monitor/examples/dependencies.json --state .loopmaster/state/dependency-release-monitor.json --output-dir docs/dependencies
Then read the generated report path printed as DEPENDENCY_RELEASE_REPORT. If RECOMMEND_ACT is greater than 0, summarize each act recommendation with confidence, risk, evidence URL, and whether the action is gated. Create follow-up kanban cards only for evidence-backed high-risk or low-confidence releases. Do not edit dependency files, merge updates, change credentials, or publish public claims without human approval. Complete with the report path, state path, counts, and any cards created.

Using Hermes native cron job scheduling from an agent session:

cronjob(action="create", name="Loopmaster dependency release monitor", schedule="0 10 * * 1", workdir="/absolute/path/to/repo", prompt="<the self-contained prompt above>")

Expected result: the scheduler returns a job id. On each run, completion evidence must include DEPENDENCY_RELEASE_REPORT, DEPENDENCY_RELEASE_STATE, DEPENDENCIES_CHECKED, NEW_RELEASES, RECOMMEND_ACT, and FETCH_ERRORS.

Failure branches:

• no kanban or scheduler backend exists — use cron or GitHub Actions instead.
• agent creates tasks without running the helper — reject the run; the backend is misinstalled because this template's verification requires the concrete helper output.
• agent edits dependency files or tries to merge an update — block for human approval as declared in human_gates.required_for.

6. Final install verification checklist

Before calling an install complete, record:

uv run --with check-jsonschema --with pyyaml check-jsonschema \
  --schemafile spec/loop.schema.json \
  templates/dependency-release-monitor/loop.yaml
rm -rf /tmp/loopmaster-dependency-release-monitor /tmp/loopmaster-dependency-release-monitor-state.json
python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py \
  --dependencies templates/dependency-release-monitor/examples/dry-run-dependencies.json \
  --state /tmp/loopmaster-dependency-release-monitor-state.json \
  --output-dir /tmp/loopmaster-dependency-release-monitor \
  --max-releases 5
python3 templates/dependency-release-monitor/scripts/dependency_release_monitor.py \
  --dependencies templates/dependency-release-monitor/examples/dry-run-dependencies.json \
  --state /tmp/loopmaster-dependency-release-monitor-state.json \
  --output-dir /tmp/loopmaster-dependency-release-monitor \
  --max-releases 5

Expected success:

ok -- validation done
DEPENDENCY_RELEASE_REPORT=/tmp/loopmaster-dependency-release-monitor/YYYY-MM-DD-dependency-release-monitor.md
DEPENDENCY_RELEASE_STATE=/tmp/loopmaster-dependency-release-monitor-state.json
DEPENDENCIES_CHECKED=2
NEW_RELEASES=2
RECOMMEND_ACT=1
FETCH_ERRORS=0
DEPENDENCY_RELEASE_REPORT=/tmp/loopmaster-dependency-release-monitor/YYYY-MM-DD-dependency-release-monitor.md
DEPENDENCY_RELEASE_STATE=/tmp/loopmaster-dependency-release-monitor-state.json
DEPENDENCIES_CHECKED=2
NEW_RELEASES=0
RECOMMEND_ACT=0
FETCH_ERRORS=0

If any expected line is missing, the install is not verified.