Loop template

tested 2026-07-07 ✓catalog data (JSON)

Link & Source Check Loop

Check Loopmaster documentation and resource URLs, update safe maintenance stamps, and escalate source updates.

Human guide

Raw README.md

Loopmaster maintenance loops

This directory contains Loopmaster's own self-maintenance loop manifests. Each *.loop.yaml file declares a recurring maintenance loop using the draft v0.1 manifest format in spec/loop-spec-v0.1.md.

Current loops:

  • link-audit.loop.yaml — checks documentation and resource URLs, writes reports to loops/log/, and escalates non-trivial source replacement.
  • landscape-watch.loop.yaml — Loopmaster's own instance of the research-watch template. Polls the AI loop / agent-tooling landscape weekly and writes cited findings reports to docs/research/. Findings publish autonomously; public positioning or recommendation changes require maintainer approval.
  • resource-discovery.loop.yaml — sweeps committed sources plus rotating queries weekly, dedupes against the resource library, writes candidate reports to loops/log/, and records review-only proposal YAML under loops/proposals/. Publishing entries to resources/resources.yaml is gated.
  • loopmaster-content-freshness.loop.yaml — Loopmaster's own instance of the content-freshness template. Audits public docs, learning content, template guides, maintenance logs, and resource metadata monthly, writes dated reports to loops/log/, and keeps rewrites/deletions/product-positioning changes human-gated.

Scheduled runs use GitHub Actions where possible so audit evidence, safe automated changes, and failures remain visible in the repository history.

The job description (loop.yaml)

View raw loop.yaml

loops/link-audit.loop.yaml

spec_version: "0.1"
id: link-audit
name: Link & Source Audit Loop
purpose: Check Loopmaster documentation and resource URLs, update safe maintenance stamps, and escalate source replacement.
audience:
  - human
  - agent
  - operator
trigger:
  type: schedule
  default: weekly
  schedule: "23 10 * * 1"
inputs:
  files:
    - README.md
    - docs/
    - templates/
    - resources/resources.yaml
capabilities:
  - url_checking
  - markdown_report
  - trivial_redirect_rewrite
  - resource_status_stamping
permissions:
  allowed_actions:
    - read_repo
    - read_web
    - write_report
    - update_same_host_redirects
    - stamp_resource_status
  forbidden_actions:
    - replace_sources_without_approval
    - publish_publicly_without_approval
    - spend_money
    - change_credentials
  credential_scopes:
    - contents:write_for_scheduled_report_commits
state:
  paths:
    - loops/log/YYYY-MM-DD-link-audit.md
  retention: permanent_audit_trail
outputs:
  artifacts:
    - loops/log/YYYY-MM-DD-link-audit.md
  tasks:
    - report_dead_or_nontrivial_source_replacement_for_human_review
verification:
  required:
    - scans URLs in docs, templates, top-level README, and resources/resources.yaml
    - report contains the five self-maintenance sections from docs/SELF-MAINTENANCE-BRIEF.md
    - dead links are detected and produce a non-zero exit
    - autonomous changes are limited to same-host redirect rewrites and resource status stamps
  commands:
    - name: run link audit and write report
      run: uv run --with pyyaml python tools/link_audit.py --write
      expected: writes loops/log/YYYY-MM-DD-link-audit.md and exits non-zero only when dead links are found
    - name: verify dead-link detection
      run: uv run --with pyyaml python tools/link_audit.py --no-report --extra-url https://example.com/__loopmaster_dead_link_probe__
      expected: exits non-zero and reports one dead URL
human_gates:
  required_for:
    - non_trivial_source_replacement
    - public_publishing_changes
    - credential_changes
  approver: maintainer
failure_policy:
  retry: 2
  escalate_after: dead_link_or_repeated_unchecked_source
  rollback: keep the previous verified resource metadata and report the failed audit in loops/log
maintenance:
  freshness_cadence: weekly
  owner: Loopmaster maintainers
  audit_log: loops/log/
backends:
  github_actions:
    schedule: "23 10 * * 1"
    workflow: .github/workflows/link-audit.yml
    install_notes:
      - Chosen scheduler is GitHub Actions cron so maintenance evidence lives with the repository.
      - Weekly runs commit the generated report and safe same-host redirect/resource-stamp updates back to main.
      - Dead links or non-trivial replacements fail the workflow after writing the report so a human can review the escalation.

Install guide (for your agent)

Raw for agents

Installing Loopmaster maintenance loops

The link audit loop is installed through .github/workflows/link-audit.yml.

What the schedule does:

  1. Runs uv run --with pyyaml python tools/link_audit.py --write from the repository root every Monday at 10:23 UTC.
  2. Writes a five-part report to loops/log/YYYY-MM-DD-link-audit.md.
  3. Commits the report plus safe autonomous updates, limited to same-host/trivial redirect rewrites and resources/resources.yaml status or last_verified stamps.
  4. Fails the workflow when a dead link is detected so maintainers see the escalation.

Manual run:

uv run --with pyyaml python tools/link_audit.py --write

Dead-link probe:

uv run --with pyyaml python tools/link_audit.py --no-report --extra-url https://example.com/__loopmaster_dead_link_probe__

Human gate: do not replace a source with a different source autonomously. Record the dead or non-trivial replacement in the report and let a maintainer approve the change.

Landscape watch

The landscape watch loop is an instance of the research-watch template (templates/research-watch/loop.yaml). It is installed through .github/workflows/landscape-watch.yml and reuses templates/research-watch/scripts/research_watch.py.

What the schedule does:

  1. Runs python3 templates/research-watch/scripts/research_watch.py --report-basename landscape-watch --sources loops/sources/landscape-watch.json --state .loopmaster/state/landscape-watch.json --output-dir docs/research from the repository root every Monday at 09:30 UTC.
  2. Polls public RSS, URL, and GitHub-repo sources listed in loops/sources/landscape-watch.json (OpenAI, Hugging Face, Karpathy, Anthropic, LangChain, CrewAI, OpenAI Agents SDK, AutoGen, LangGraph, A2A, MCP, and the matching repos).
  3. Dedupes against .loopmaster/state/landscape-watch.json so repeated runs do not re-report seen items.
  4. Writes a dated, cited, five-part report to docs/research/YYYY-MM-DD-landscape-watch.md.
  5. Opens a pull request with the report and state changes. No web-search credential is required.

Manual run:

python3 templates/research-watch/scripts/research_watch.py \
  --report-basename landscape-watch \
  --sources loops/sources/landscape-watch.json \
  --state .loopmaster/state/landscape-watch.json \
  --output-dir docs/research

Dedupe check (second run reports NEW_ITEMS=0):

python3 templates/research-watch/scripts/research_watch.py \
  --report-basename landscape-watch \
  --sources loops/sources/landscape-watch.json \
  --state .loopmaster/state/landscape-watch.json \
  --output-dir docs/research

Human gate: findings publish autonomously; changes to public recommendations, positioning, or product direction require maintainer approval. Do not merge the report PR if it changes Loopmaster's public positioning.

Resource discovery

The resource-discovery loop (loops/resource-discovery.loop.yaml) is an instance of the research-watch pattern tuned for resource-library proposals. Its concrete runner is tools/resource_discovery.py, and the scheduled backend is .github/workflows/resource-discovery.yml.

What the schedule does:

  1. Runs uv run --with pyyaml python tools/resource_discovery.py --sources loops/resource-discovery.sources.json --state .loopmaster/state/resource-discovery.json --output-dir loops/log --resources resources/resources.yaml --max-items 5 every Monday at 09:30 UTC.
  2. Dedupes against both resources/resources.yaml and .loopmaster/state/resource-discovery.json.
  3. Writes a five-part report to loops/log/YYYY-MM-DD-resource-discovery.md and updates the state ledger.
  4. Opens a review-only pull request with report/state changes; scored proposal YAML can be added by an agent or maintainer after applying resources/RUBRIC.md.

Manual run:

uv run --with pyyaml python tools/resource_discovery.py \
  --sources loops/resource-discovery.sources.json \
  --state .loopmaster/state/resource-discovery.json \
  --output-dir loops/log \
  --resources resources/resources.yaml \
  --max-items 5 \
  --exploratory "rotating queries this run: ..."

Expected output shape:

RESOURCE_DISCOVERY_REPORT=loops/log/YYYY-MM-DD-resource-discovery.md
RESOURCE_DISCOVERY_STATE=.loopmaster/state/resource-discovery.json
NEW_CANDIDATES=<n>
FETCH_ERRORS=<n>

Dedupe verification: run the same command a second time against the same state and expect NEW_CANDIDATES=0.

Scoring and proposing: after a run with NEW_CANDIDATES > 0, score each candidate against resources/RUBRIC.md (five dimensions, 0–2 each). Write ready-to-merge YAML for candidates scoring ≥7 with no dimension at 0 into loops/proposals/YYYY-MM-DD-resource-discovery.proposal.yaml, and record at least one rejected candidate with scores to prove the rubric has teeth.

Human gate: do not merge proposed entries into resources/resources.yaml without maintainer approval. Proposing is autonomous; publishing is gated.

Content freshness

The content-freshness loop (loops/loopmaster-content-freshness.loop.yaml) is Loopmaster's own instance of the content-freshness template. Its concrete runner is templates/content-freshness/scripts/content_freshness.py, configured by loops/content-freshness.targets.json, and the scheduled backend is .github/workflows/content-freshness.yml.

What the schedule does:

  1. Runs python3 templates/content-freshness/scripts/content_freshness.py --targets loops/content-freshness.targets.json --state .loopmaster/state/content-freshness.json --output-dir loops/log --max-link-checks 40 monthly at 10:00 UTC on the first day of the month.
  2. Scans public docs, authored site content, template guides, maintenance-loop docs, and resource metadata for stale files, stale markers, and checked-link failures.
  3. Writes a dated report to loops/log/YYYY-MM-DD-content-freshness.md and updates .loopmaster/state/content-freshness.json.
  4. Opens a review-only pull request with the report and state changes.

Manual run:

python3 templates/content-freshness/scripts/content_freshness.py \
  --targets loops/content-freshness.targets.json \
  --state .loopmaster/state/content-freshness.json \
  --output-dir loops/log \
  --max-link-checks 40

Expected output shape:

CONTENT_FRESHNESS_REPORT=loops/log/YYYY-MM-DD-content-freshness.md
CONTENT_FRESHNESS_STATE=.loopmaster/state/content-freshness.json
FINDINGS=<n>
AUDIT_ERRORS=<n>
LINKS_CHECKED=<n>

Human gate: the loop may report stale evidence, broken links, and source-backed recommendations. Do not rewrite public copy, delete content, or change product positioning without maintainer approval.

How we know it works

Status
tested
Date
2026-07-07
Stale after
2026-08-06

dated checks passed

loops/log/2026-07-07-link-audit.md

    What it's allowed to do

    5 allowed action(s), 4 forbidden action(s), 1 credential scope(s)

    Allowed actions
    read_repo, read_web, write_report, update_same_host_redirects, stamp_resource_status
    Credential scopes
    contents:write_for_scheduled_report_commits
    Forbidden actions
    replace_sources_without_approval, publish_publicly_without_approval, spend_money, change_credentials