feat: per-repo STATUS.md 'Today's CI' refresher

protosphinx · protosphinx · commit cabbd26afea1 · 2026-05-02T19:54:30.000-07:00
Adds a second tier to the morning-triage workflow: every org repo
that has a STATUS.md at root gets a 'Today's CI' h2 section
(between BEGIN: ci-today / END: ci-today markers) that mirrors the
org-table view but scoped to that one repo — same window
(00:00 UTC), plus a link to the latest failed run if any.

Designed around the morning-agent loop: agent opens
github.com/erphq → sees the org table → clicks into a red repo →
opens STATUS.md → 'Today's CI' block tells them which run failed
+ where to look. The block lives above the human-curated TL;DR
because that's the order the agent reads in.

Mechanics:
  - scripts/build-repo-status.sh: emits the block markdown for one
    repo. Pulls test count from the README's tests-N badge,
    workflow runs since 00:00 UTC by conclusion, the latest
    failed-run URL.
  - scripts/inject-ci-today.py: idempotent insert/replace via
    BEGIN/END markers. Bootstraps a new section right after the
    H1 line on first run; replaces only the marker block on
    subsequent runs.
  - scripts/update-repo-status.sh: clones the target repo shallow,
    runs inject, commits + pushes. Race-safe (rebase-and-amend
    loop). Skips silently if the repo has no STATUS.md.
  - refresh-status.yml: a second job (refresh-per-repo) discovers
    STATUS.md-bearing repos via gh-api and runs the updater on
    each. Gated on the ORG_REFRESH_PAT secret because the default
    GITHUB_TOKEN can't write to other org repos. Without the PAT
    the per-repo job is a no-op; the org-table job still runs.

Initial seed (the 11 STATUS.md repos: codegraph, FFS, processmind,
build-host, smriti, pm-bench, vahini, karta, bija, crucible, flow)
was committed to each repo separately before this workflow change
landed, so the first cron fire just no-ops on them until tomorrow.
diff --git a/.github/workflows/refresh-status.yml b/.github/workflows/refresh-status.yml
@@ -1,16 +1,25 @@
 name: Refresh status table
 
-# Rebuilds the org-wide CI status block in profile/README.md so the
-# org page (https://github.com/erphq) always shows yesterday's run
-# tally + current per-repo test counts. The intended audience is an
-# agent that opens the org page each morning to triage what to fix.
+# Two-tier status refresh for the morning-triage workflow:
 #
-# Cadence: hourly during the day, plus a manual trigger. Hourly is
-# light: ~30 small gh-api reads + one repo edit at most.
+#   1. profile/README.md (this repo) — public org-wide table showing
+#      every public repo's tests + today's run tally. The org page at
+#      https://github.com/erphq surfaces this directly.
 #
-# Auth: cross-repo reads of private org repos need a PAT scoped to
-# `repo`. Store it as the org/repo secret `ORG_REFRESH_PAT`. Without
-# it, the workflow still runs but private-repo run tallies show zero.
+#   2. STATUS.md in each org repo that has one — per-repo "Today's CI"
+#      block (between BEGIN/END markers) so an agent that's already
+#      landed in a specific repo sees today's run/pass/fail/latest-
+#      failure-link without leaving the file they're reading.
+#
+# Cadence: hourly. Light: a couple dozen gh-api reads + one edit per
+# repo that actually changed.
+#
+# Auth: the per-repo update step writes to OTHER repos in the org, so
+# it needs a PAT scoped to `repo` (or a fine-grained PAT with
+# Contents: Write on org repos). Store it as the repo secret
+# `ORG_REFRESH_PAT`. Without it, the per-repo refresh job is skipped
+# (the org-table job still works on the default GITHUB_TOKEN since
+# it only reads + edits this repo).
 
 on:
   schedule:
@@ -22,6 +31,9 @@ on:
     branches: [main]
     paths:
       - 'scripts/build-status-table.sh'
+      - 'scripts/build-repo-status.sh'
+      - 'scripts/update-repo-status.sh'
+      - 'scripts/inject-ci-today.py'
       - '.github/workflows/refresh-status.yml'
 
 permissions:
@@ -98,3 +110,42 @@ jobs:
           done
           echo "::error::push failed after 3 attempts"
           exit 1
+
+  refresh-per-repo:
+    # Updates each org repo's STATUS.md "Today's CI" block.
+    # Independent of the org-table job above so a per-repo failure
+    # doesn't take down the org-page refresh.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Only runs when ORG_REFRESH_PAT is configured — without it we
+    # can't write to the other org repos (default GITHUB_TOKEN is
+    # repo-scoped to .github only).
+    if: ${{ vars.RUN_PER_REPO_REFRESH != 'false' }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Update each repo's STATUS.md
+        env:
+          GH_TOKEN: ${{ secrets.ORG_REFRESH_PAT || secrets.GITHUB_TOKEN }}
+          ORG: erphq
+        run: |
+          if [[ -z "${{ secrets.ORG_REFRESH_PAT }}" ]]; then
+            echo "ORG_REFRESH_PAT not set — per-repo refresh would only be"
+            echo "able to read/write this .github repo. Skipping."
+            exit 0
+          fi
+
+          # Discover repos that have a STATUS.md at root. Survey is
+          # cheap (one /contents/STATUS.md HEAD per repo) and means
+          # we don't have to maintain a hand-curated list — a new
+          # repo gets the block as soon as it has STATUS.md.
+          repos=$(gh api "orgs/$ORG/repos" --paginate -q '.[] | select(.archived | not) | .name')
+          for repo in $repos; do
+            if gh api "repos/$ORG/$repo/contents/STATUS.md" -q .name >/dev/null 2>&1; then
+              echo "::group::$repo"
+              # Each invocation is independent — a single repo failure
+              # shouldn't break the rest. Use `|| true` to swallow.
+              bash scripts/update-repo-status.sh "$repo" || echo "::warning::$repo update failed"
+              echo "::endgroup::"
+            fi
+          done
diff --git a/scripts/build-repo-status.sh b/scripts/build-repo-status.sh
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Builds the "Today's CI" status block for a single repo. Goes between
+# the BEGIN: ci-today / END: ci-today markers in that repo's STATUS.md.
+# Companion to scripts/build-status-table.sh (which builds the org-wide
+# table that lives in this repo's profile/README.md).
+#
+# Usage:
+#   ORG=erphq scripts/build-repo-status.sh REPO_NAME > /tmp/repo-status.md
+#
+# Pulls live from the GitHub API:
+#   - test count: from README's "tests-N passing" shields.io badge
+#   - run tally since 00:00 UTC today, by conclusion
+#   - the latest failed workflow run (with URL) — what an agent landing
+#     in this repo each morning needs to start triaging
+#   - open PRs whose head SHA has a failed check — the work to do
+#
+# Requires: gh (authed with cross-repo read), jq.
+
+set -euo pipefail
+
+ORG="${ORG:-erphq}"
+REPO="${1:?usage: ORG=erphq $0 REPO_NAME}"
+SINCE="$(date -u +%Y-%m-%dT00:00:00Z)"
+TODAY="$(date -u +%Y-%m-%d)"
+
+# Test count from the README badge. Returns "—" if the repo has no
+# badge (e.g. neo-releases, skills — repos that don't ship code tests).
+fetch_test_count() {
+  local body
+  body=$(gh api "repos/$ORG/$REPO/readme" -q .content 2>/dev/null | base64 -d 2>/dev/null || true)
+  if [[ -z "$body" ]]; then
+    echo "—"
+    return
+  fi
+  local n
+  n=$(printf '%s' "$body" | sed -nE 's|.*tests-([0-9]+)%20passing.*|\1|p' | head -1)
+  if [[ -z "$n" ]]; then
+    echo "—"
+  else
+    echo "$n"
+  fi
+}
+
+# Pull all workflow runs created since 00:00 UTC today, then summarise.
+runs_json=$(gh api "repos/$ORG/$REPO/actions/runs?created=>=$SINCE&per_page=100" 2>/dev/null || echo '{"workflow_runs":[]}')
+
+total=$(printf '%s' "$runs_json" | jq '.workflow_runs | length')
+pass=$(printf '%s' "$runs_json" | jq '[.workflow_runs[] | select(.conclusion == "success")] | length')
+fail=$(printf '%s' "$runs_json" | jq '[.workflow_runs[] | select(.conclusion == "failure")] | length')
+other=$((total - pass - fail))
+tests=$(fetch_test_count)
+
+# Latest failed run today (if any), for the "where to look first" link.
+latest_fail_url=$(printf '%s' "$runs_json" | jq -r '[.workflow_runs[] | select(.conclusion == "failure")] | sort_by(.created_at) | reverse | .[0].html_url // ""')
+latest_fail_name=$(printf '%s' "$runs_json" | jq -r '[.workflow_runs[] | select(.conclusion == "failure")] | sort_by(.created_at) | reverse | .[0].name // ""')
+latest_fail_branch=$(printf '%s' "$runs_json" | jq -r '[.workflow_runs[] | select(.conclusion == "failure")] | sort_by(.created_at) | reverse | .[0].head_branch // ""')
+
+# Open PRs with at least one failing check. Cap at 5 so the block stays
+# tight; if there are more, the link to the org PR list covers the rest.
+prs_json=$(gh pr list -R "$ORG/$REPO" --state open --limit 30 --json number,title,headRefOid,statusCheckRollup 2>/dev/null || echo '[]')
+red_prs=$(printf '%s' "$prs_json" | jq -r '
+  [.[] | select(
+     (.statusCheckRollup // []) | map(
+       (.conclusion // .status // "") | ascii_downcase
+     ) | any(. == "failure" or . == "fail")
+  )] | .[0:5] | .[] |
+  "  - [#" + (.number | tostring) + "](https://github.com/'"$ORG"'/'"$REPO"'/pull/" + (.number | tostring) + ") — " + .title
+')
+
+# Render. Trailing newline-free so the marker block stays compact.
+cat <<EOF
+_Auto-refreshed by [\`erphq/.github/refresh-status.yml\`](https://github.com/erphq/.github/blob/main/.github/workflows/refresh-status.yml). Window: runs created since 00:00 UTC on $TODAY (\`$SINCE\`)._
+
+| Tests | Runs today | ✅ pass | ❌ fail | ⚠️ other |
+|---:|---:|---:|---:|---:|
+| **$tests** | **$total** | **$pass** | **$fail** | **$other** |
+EOF
+
+if [[ -n "$latest_fail_url" ]]; then
+  echo
+  echo "**Latest failed run:** [$latest_fail_name on \`$latest_fail_branch\`]($latest_fail_url)"
+fi
+
+if [[ -n "$red_prs" ]]; then
+  echo
+  echo "**Open PRs with failing checks:**"
+  echo "$red_prs"
+fi
diff --git a/scripts/inject-ci-today.py b/scripts/inject-ci-today.py
@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# Reads $BLOCK_FILE and injects its contents into STATUS.md (in CWD)
+# between the BEGIN: ci-today / END: ci-today markers. If the markers
+# don't exist yet, prepends a new "Today's CI" h2 right after the
+# first H1 line. Exit 42 if STATUS.md is already up-to-date.
+#
+# Used by update-repo-status.sh — kept as its own file so the bash
+# script doesn't have to bash-interpolate arbitrary content into a
+# python heredoc (block content includes backticks, brackets, pipes,
+# could later include quote characters).
+
+import os
+import pathlib
+import re
+import sys
+
+block = pathlib.Path(os.environ['BLOCK_FILE']).read_text().strip()
+path = pathlib.Path('STATUS.md')
+src = path.read_text()
+
+BEGIN = '<!-- BEGIN: ci-today -->'
+END = '<!-- END: ci-today -->'
+
+if BEGIN in src and END in src:
+    new = re.sub(
+        re.escape(BEGIN) + r'\n.*?\n' + re.escape(END),
+        BEGIN + '\n' + block + '\n' + END,
+        src,
+        count=1,
+        flags=re.S,
+    )
+else:
+    # Insert a fresh "Today's CI" h2 right after the first H1 line.
+    # Picked the position because every STATUS.md in the org follows
+    # the "# Title \n one-line summary \n ## first section" shape, so
+    # the "Today" block lands above the human-curated TL;DR — that's
+    # the order an agent doing a morning triage wants to read.
+    section = (
+        '\n## Today’s CI\n\n'
+        + BEGIN + '\n'
+        + block + '\n'
+        + END + '\n'
+    )
+    lines = src.splitlines(keepends=True)
+    insert_at = 0
+    for i, line in enumerate(lines):
+        if line.startswith('# '):
+            insert_at = i + 1
+            break
+    if insert_at < len(lines) and lines[insert_at].strip() == '':
+        insert_at += 1
+    new = ''.join(lines[:insert_at]) + section + ''.join(lines[insert_at:])
+
+repo = os.environ.get('REPO_NAME', '?')
+if new == src:
+    print(f'[{repo}] no change')
+    sys.exit(42)
+path.write_text(new)
+print(f'[{repo}] updated')
diff --git a/scripts/update-repo-status.sh b/scripts/update-repo-status.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Updates one repo's STATUS.md "Today's CI" block in place.
+# - If the repo has STATUS.md and the BEGIN: ci-today / END: ci-today
+#   markers are already present: replace the block content.
+# - If the repo has STATUS.md but no markers: prepend a new "Today" h2
+#   section with the markers right after the title line (first H1).
+# - If the repo has no STATUS.md: skip (no-op exit 0).
+#
+# Commits + pushes via gh-cli auth. Skips the commit if the block
+# content is byte-identical to what's already in the repo (idempotent).
+#
+# Usage:
+#   ORG=erphq scripts/update-repo-status.sh REPO_NAME
+
+set -euo pipefail
+
+ORG="${ORG:-erphq}"
+REPO="${1:?usage: ORG=erphq $0 REPO_NAME}"
+
+HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+
+# Bail early if the repo doesn't have STATUS.md at the root.
+if ! gh api "repos/$ORG/$REPO/contents/STATUS.md" -q .name >/dev/null 2>&1; then
+  echo "[$REPO] no STATUS.md at root — skip"
+  exit 0
+fi
+
+# Build the block, write to a temp file (safer than bash-interpolating
+# arbitrary content into a python heredoc — content includes backticks,
+# pipes, brackets, and could later include quote characters).
+block_file=$(mktemp)
+trap 'rm -f "$block_file"' EXIT
+ORG="$ORG" "$HERE/build-repo-status.sh" "$REPO" > "$block_file"
+export BLOCK_FILE="$block_file"
+export REPO_NAME="$REPO"
+
+# Clone shallow; .git stays for the commit.
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+gh repo clone "$ORG/$REPO" "$work" -- --depth=1 --quiet
+cd "$work"
+
+python3 "$HERE/inject-ci-today.py"
+status=$?
+if [[ $status -eq 42 ]]; then
+  echo "[$REPO] no change — skip commit"
+  exit 0
+fi
+if [[ $status -ne 0 ]]; then
+  echo "[$REPO] inject failed"
+  exit "$status"
+fi
+
+git config user.name 'github-actions[bot]'
+git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+git add STATUS.md
+if git diff --cached --quiet; then
+  echo "[$REPO] no change after stage — skip"
+  exit 0
+fi
+git commit -m "chore(status): refresh today's CI block"
+# Race-safe: if push loses, re-pull and re-inject. We can do that here
+# because no human edits the marker block between BEGIN/END.
+for attempt in 1 2 3; do
+  if git push; then
+    echo "[$REPO] pushed"
+    exit 0
+  fi
+  echo "[$REPO] push raced (attempt $attempt) — pulling and retrying"
+  git fetch origin --quiet
+  git reset --hard origin/HEAD --quiet || git reset --hard "origin/$(git rev-parse --abbrev-ref HEAD)" --quiet
+  # Re-run the same inject path on the new base.
+  python3 "$HERE/inject-ci-today.py" || true
+  if git diff --quiet STATUS.md; then
+    echo "[$REPO] no diff after rebase — done"
+    exit 0
+  fi
+  git add STATUS.md
+  git commit --amend --no-edit >/dev/null
+done
+echo "::error::[$REPO] push failed after 3 attempts"
+exit 1
