diff --git a/.github/workflows/context-cadence.yml b/.github/workflows/context-cadence.yml index f2cf17b..4ae2120 100644 --- a/.github/workflows/context-cadence.yml +++ b/.github/workflows/context-cadence.yml @@ -6,8 +6,9 @@ name: context-cadence # # It does NOT curate. Curation needs judgement — classify each section, verify # each claim, decide what relocates where — and that stays agent-triggered, -# prompted by what these rows show. Rationale and the annotated template: -# curating-context/references/cadence.md +# prompted by what these rows show. Rationale: +# curating-context/references/cadence.md — and this file annotated step by step: +# curating-context/references/cadence/workflow.md # # Generated by install-cadence.sh. Re-run it rather than editing by hand. # @@ -24,6 +25,9 @@ on: # append-only telemetry, not code. permissions: contents: write + # pull-requests: write because .skills/merge_mode said `pr` when this was + # rendered (#560): the row goes to one standing PR, not the default branch. + pull-requests: write concurrency: group: context-cadence @@ -45,11 +49,11 @@ jobs: # fetch-depth: 0 because the push path rebases when a human commit lands # during the measurement, and rebasing on a depth-1 clone lacks the history # to replay onto. - # @v5, not @v4: v4 targets Node 20, which runners now force onto Node 24 - # with a deprecation warning on every run. Twelve repos are about to adopt - # this template, and sweeping twelve for a warning we could have not - # written is the avoidable version of the problem (#163). - - uses: actions/checkout@v5 + # Never below @v5: v4 targets Node 20, which runners force onto Node 24 + # with a deprecation warning on every run (#163). The template's pin is + # only a floor: a re-render keeps an installed SHA pin, or an installed + # major at or above the template's, so a Dependabot bump survives (#373). + - uses: actions/checkout@v7 with: submodules: recursive fetch-depth: 0 @@ -57,20 +61,109 @@ jobs: - name: Heal vendored symlinks run: '[ ! -x .skills/doctor.sh ] || bash .skills/doctor.sh' + # .skills/merge_mode (#342), read from this checkout with merge-mode.sh's + # grammar: one word, blank lines and whole-line `#` comments ignored. + # Inline because a consumer need not vendor shipping-work, which ships + # that script. Absent is `direct`. Present but unusable fails HERE, before + # the credential is spent, and is never read as `direct` (#560). + - name: Read the merge mode + run: | + K=.skills/merge_mode + R="write one word, 'pr' or 'direct', or delete the file for the default ('direct')" + M=direct + if [ -e "$K" ] || [ -L "$K" ]; then + { [ -f "$K" ] && [ -r "$K" ]; } || { echo "::error::$K is present but not a readable file: $R"; exit 2; } + M='' N=0 + while IFS= read -r L || [ -n "$L" ]; do + L=${L%$'\r'} + read -r -a W <<<"$L" + [ "${#W[@]}" -gt 0 ] || continue + case ${W[0]} in \#*) continue ;; esac + N=$((N + ${#W[@]})) M=${W[0]} + done <"$K" + [ "$N" -gt 0 ] || { echo "::error::$K names no mode: $R"; exit 2; } + [ "$N" -eq 1 ] || { echo "::error::$K has $N words; it takes one: $R"; exit 2; } + case $M in + pr | direct) ;; + *) echo "::error::$K says '$M', which is not a merge mode: $R"; exit 2 ;; + esac + fi + echo "merge mode: $M" + echo "MERGE_MODE=$M" >>"$GITHUB_ENV" + + # One path per script, each probed on its own and exported under its own + # name: measure-context.sh as MEASURE_CONTEXT_SH, and so on. Never one + # directory for all of them — a project scripts/ holding only + # measure-context.sh sent every other script to a directory that lacked + # it (#301). A script found nowhere fails this step, by name. - name: Resolve the skill scripts run: | - N=curating-context S=measure-context.sh SD= - for d in scripts ".claude/skills/$N/scripts" "skills/$N/scripts"; do - [ -f "$d/$S" ] && { SD="$d"; break; } + N=curating-context + for S in measure-context.sh check-seams.sh check-counts.sh record-telemetry.sh merge-token-counts.sh; do SD= + for d in scripts ".claude/skills/$N/scripts" "skills/$N/scripts"; do + [ -f "$d/$S" ] && { SD="$d"; break; } + done + V=$(printf %s "$S" | tr 'a-z.-' 'A-Z__') + echo "$V=${SD:?$S not found in scripts/, .claude/skills/$N/scripts/, or skills/$N/scripts/}/$S" >>"$GITHUB_ENV" done - echo "SKILL_SCRIPTS=${SD:?curating-context scripts not found}" >>"$GITHUB_ENV" # FIRST, not last: without a credential every later step does its work and - # the append is refused at the end. + # the append is refused at the end. This asks the endpoint whether it + # accepts the secret, so a key that authenticates but cannot spend reddens + # here rather than at the last step (#271). - name: Preflight the credential env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - run: bash "$SKILL_SCRIPTS/measure-context.sh" --check-credential + run: bash "$MEASURE_CONTEXT_SH" --check-credential + + # merge_mode pr (#560): the checkout is the default branch, whose ledger + # lacks the rows still on context/weekly-measurement. Measured there, a + # row took its deltas, and the seam sweep its --base-ledger interval, + # from the last MERGED row: the delta check warned on every run while + # the PR stayed open, and the merge landed those deltas. So when the + # push below would keep the branch, it is merged in before the sweep. + # --no-commit: HEAD stays the default branch's tip, so the row's + # repo_commit is a commit that branch keeps, and the commit step + # records the merge with the row. Which PR is decided as the push + # decides it, and the push decides again: a PR can merge mid-run. + - name: Take in the measurement PR's rows + env: + GH_TOKEN: ${{ github.token }} + run: | + [ "${MERGE_MODE:-}" = pr ] || { echo "merge mode ${MERGE_MODE:-unset}: no PR's rows to take in"; exit 0; } + BRANCH="${GITHUB_REF_NAME:-$(git branch --show-current)}" + PR_BRANCH=context/weekly-measurement + PRS=$(gh pr list --head "$PR_BRANCH" --base "$BRANCH" --state all --json number,state,headRefOid,isCrossRepository --jq '.[] | select(.isCrossRepository | not) | "\(.number) \(.state) \(.headRefOid)"') || { + echo "::error::gh pr list failed, so which measurement PR is open is unknown — nothing was measured." + exit 1; } + REMOTE=$(git ls-remote origin "refs/heads/$PR_BRANCH") || { + echo "::error::could not read $PR_BRANCH from origin — nothing was measured." + exit 1; } + TIP=${REMOTE%%[[:space:]]*} + OPEN='' ENDED='' + while read -r N S OID; do + [ -n "$N" ] || continue + if [ "$S" = OPEN ]; then + OPEN=${OPEN:-$N} + elif [ -n "$TIP" ] && [ "$OID" = "$TIP" ]; then + ENDED=$N + fi + done <<<"$PRS" + if [ -n "$TIP" ] && { [ -n "$OPEN" ] || [ -z "$ENDED" ]; }; then + # The commit step sets these too; the merge needs them now. + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config merge.ours.driver true + git config merge.context-counts.driver "bash \"$MERGE_TOKEN_COUNTS_SH\" %O %A %B %P" + { git fetch -q origin "+refs/heads/$PR_BRANCH:refs/remotes/origin/$PR_BRANCH" \ + && git merge -q --no-commit --no-ff "$TIP"; } || { + echo "::error::could not merge $PR_BRANCH in — nothing was measured." + git diff --name-only --diff-filter=U | sed 's/^/::error:: conflicted: /' + exit 1; } + echo "measuring after the rows on $PR_BRANCH${OPEN:+ (PR #$OPEN)}" + else + echo "no rows on $PR_BRANCH to take in: the row is measured after $BRANCH's" + fi # Exits 3 when there are new seams, which is a finding rather than a # failure here — the count goes on the row either way. @@ -82,12 +175,29 @@ jobs: # newest repo_commit is the previous measurement, so the sweep spans the # interval since it. With no such row the report SAYS the interval is # empty rather than presenting a standing count as a week's accrual. - - name: Sweep the seams + - name: Sweep the seams and the counts run: | - bash "$SKILL_SCRIPTS/check-seams.sh" --base-ledger ".skills/context-metrics.jsonl" >/tmp/seams.txt 2>&1 || true - tail -20 /tmp/seams.txt - echo "SEAMS=$(sed -n 's/^seams: \([0-9]*\)$/\1/p' /tmp/seams.txt | tail -1)" >>"$GITHUB_ENV" - echo "SEAMS_ACKED=$(sed -n 's/^seams_acked: \([0-9]*\)$/\1/p' /tmp/seams.txt | tail -1)" >>"$GITHUB_ENV" + # Files of its own (#526): a fixed /tmp path is shared with every + # other run on the machine, which can truncate it between two reads. + SEAMS_OUT=$(mktemp) COUNTS_OUT=$(mktemp) + trap 'rm -f "$SEAMS_OUT" "$COUNTS_OUT"' EXIT + bash "$CHECK_SEAMS_SH" --base-ledger ".skills/context-metrics.jsonl" >"$SEAMS_OUT" 2>&1 || true + tail -20 "$SEAMS_OUT" + SEAMS=$(sed -n 's/^seams: \([0-9]*\)$/\1/p' "$SEAMS_OUT" | tail -1) + SEAMS_ACKED=$(sed -n 's/^seams_acked: \([0-9]*\)$/\1/p' "$SEAMS_OUT" | tail -1) + # Same step, same shape (#258): without it the scheduled row carries + # a null counts field forever and the class is recorded only by + # hand-run curations — #169's shape, one field over. + bash "$CHECK_COUNTS_SH" >"$COUNTS_OUT" 2>&1 || true + tail -20 "$COUNTS_OUT" + COUNTS=$(sed -n 's/^counts: \([0-9]*\)$/\1/p' "$COUNTS_OUT" | tail -1) + COUNTS_ACKED=$(sed -n 's/^counts_acked: \([0-9]*\)$/\1/p' "$COUNTS_OUT" | tail -1) + # An empty count is a lost count, not a zero (#526): fail before + # GITHUB_ENV rather than record the row with the field missing. + for kv in "SEAMS=$SEAMS" "SEAMS_ACKED=$SEAMS_ACKED" "COUNTS=$COUNTS" "COUNTS_ACKED=$COUNTS_ACKED"; do + [ -n "${kv#*=}" ] || { echo "::error::no ${kv%%=*} count in the sweep's output"; exit 1; } + done + printf '%s\n' "SEAMS=$SEAMS" "SEAMS_ACKED=$SEAMS_ACKED" "COUNTS=$COUNTS" "COUNTS_ACKED=$COUNTS_ACKED" >>"$GITHUB_ENV" # Measured ONCE — the drift report below reads this file rather than # re-running --exact, which would disagree with the row just recorded. @@ -95,13 +205,16 @@ jobs: env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | - bash "$SKILL_SCRIPTS/measure-context.sh" --exact >/tmp/ctx.json - bash "$SKILL_SCRIPTS/record-telemetry.sh" --baseline=scheduled \ + bash "$MEASURE_CONTEXT_SH" --exact >/tmp/ctx.json + bash "$RECORD_TELEMETRY_SH" --baseline=scheduled \ --ledger ".skills/context-metrics.jsonl" \ ${SEAMS:+--seams "$SEAMS"} ${SEAMS_ACKED:+--seams-acked "$SEAMS_ACKED"} \ + ${COUNTS:+--counts "$COUNTS"} ${COUNTS_ACKED:+--counts-acked "$COUNTS_ACKED"} \ --print-trend "$PUSH_OUT" 2>&1; then + cat "$PUSH_OUT" + echo "::error::push to $PR_BRANCH refused — the row was not pushed." + if grep -qE 'GH013|protected branch' "$PUSH_OUT"; then + echo "::error::A ruleset or branch protection covers $PR_BRANCH too. Exempt it: this job only opens a PR from it." + fi + exit 1 + fi + cat "$PUSH_OUT" + if [ -n "$OPEN" ]; then + echo "updated PR #$OPEN with this run's row" + exit 0 + fi + # A PR opened with GITHUB_TOKEN starts no pull_request workflow, + # so a required check never runs on it until a human acts. + CREATE_ERR=$(mktemp) + gh pr create --base "$BRANCH" --head "$PR_BRANCH" \ + --title "chore: weekly context measurement" \ + --body "Opened by the context-cadence workflow, because .skills/merge_mode is pr. Each run appends its row to this branch while this PR is open. It was opened with GITHUB_TOKEN, so no pull_request workflow runs on it: if a required check blocks the merge, close and reopen this PR to start them." \ + 2>"$CREATE_ERR" && exit 0 + cat "$CREATE_ERR" + echo "::error::the row is on $PR_BRANCH, but no PR was opened for it. The next run keeps it and tries again." + if grep -q 'not permitted to create or approve pull requests' "$CREATE_ERR"; then + echo "::error::Turn on Settings > Actions > General > Workflow permissions > \"Allow GitHub Actions to create and approve pull requests\" (an organization can hold it off at its own level), then re-run this workflow." + fi + exit 1 + ;; + *) + echo "::error::no merge mode (MERGE_MODE='${MERGE_MODE:-}'): the Read the merge mode step did not run — the row was not pushed." + exit 1 + ;; + esac for attempt in 1 2 3; do git push origin "HEAD:$BRANCH" && exit 0 echo "push rejected (attempt $attempt) — rebasing onto origin/$BRANCH" @@ -188,11 +388,71 @@ jobs: fi python3 - /tmp/ctx.json <<'PY' import json, sys - p = json.load(open(sys.argv[1]))["policy"] - if p["over_budget"]: - print(f"::warning::{p['path']} is {p['tokens']} tokens against a " - f"{p['budget']} budget. Run `curate context` in this repo.") + + d = json.load(open(sys.argv[1])) + # Every live doc, not the policy file alone. Both tiers, and why the + # second is quieter: cadence.md (#273). + rows = [r for r in [d["policy"], *(d.get("docs") or [])] + if isinstance(r, dict) and r.get("budget") + and isinstance(r.get("tokens"), int)] + + + def num(r): + # A precise count is a claim an ESTIMATED row cannot make; the + # number is marked, not the row dropped (#123). + s = r.get("tokens_source") + if s == "exact": + return str(r["tokens"]), "" + return "~%s" % r["tokens"], f" — an estimate ({s or 'source unstated'}), not a count" + + + # Breaches first, then approaches, at different levels on purpose. + for r in rows: + if r.get("over_budget"): + n, est = num(r) + print(f"::warning::{r['path']} is {n} tokens against a {r['budget']} " + f"budget{est}. Run `curate context` in this repo.") + for r in rows: + if r.get("near_budget"): + n, est = num(r) + print(f"::notice::{r['path']} is approaching its budget: {n} tokens of " + f"{r['budget']}, {r['budget'] - r['tokens']} left{est}. Not over — " + f"the cheap moment to decide where the next section goes.") + # Older scripts than this workflow; every key read below the filter + # is filtered on, so no row can raise past it. + skipped = 1 + len(d.get("docs") or []) - len(rows) + if skipped: + print(f"::warning::{skipped} measured row(s) carry no budget or token count, " + f"so their budget position went unreported — the measuring scripts are " + f"older than this workflow. Re-run install-cadence.sh.") PY + if [ "${COUNTS:-0}" -gt 0 ]; then + echo "::warning::$COUNTS unjudged count(s) or over-long index line(s). Run \`curate context\`." + fi if [ "${SEAMS:-0}" -gt 0 ]; then echo "::warning::$SEAMS unacknowledged cross-reference seam(s). Run \`curate context\`." fi + + # The ledger merges with merge=union, so a curation branch that merged or + # rebased this branch in while it was open can land a row between two + # others — cleanly, with nothing to signal it — and the later row's + # deltas then describe a row that is no longer before it (#325). Three + # of the first cohort's thirteen ledgers had one. --dry-run only: this + # job appends and never rewrites, so the repair is a commit for whoever + # reads the warning. Its stdout is empty on a clean ledger. always(), + # like the drift report, so a failed push does not hide it. + - name: Check the recorded deltas + if: always() + run: | + if [ -z "${RECORD_TELEMETRY_SH:-}" ]; then + echo "the skill scripts were not resolved — see the failing step above" + exit 0 + fi + # --repair reads origin/HEAD, which checkout does not set. Tolerated: + # without it --repair says so itself, and still checks the deltas. + git remote set-head origin --auto >/dev/null 2>&1 || true + bash "$RECORD_TELEMETRY_SH" --repair --dry-run --ledger ".skills/context-metrics.jsonl" >/tmp/deltas.jsonl + if [ -s /tmp/deltas.jsonl ]; then + echo "::warning::$(wc -l `. Nothing *enforces* this yet: `main` has no +ruleset, so a by-hand `git push origin main` still lands. + +- **Merge with a merge commit.** It keeps each `# type:` commit. Its own title is + GitHub's `Merge pull request #N from …`, and nothing here checks that title. A squash + title has to be written to the commit convention by hand. +- **Deploy and roll back to merge commits.** The push to `main` gives the merge commit its + CI run. A commit *inside* a merged PR has no push run of its own, because its PR checks ran + on GitHub's `refs/pull/N/merge`. So `scripts/deploy.sh ` refuses it: name a merge + commit (from before #208's, a push tip that isn't the cadence bot's). +- **After any merge on GitHub,** `git pull --ff-only` before the next local commit. +- **Two bots open PRs too:** + - **The skills refresh hook** keeps one PR from `skills/submodule-refresh` + ([SKILLS.md](SKILLS.md#maintenance)). + - **The weekly cadence** keeps one from `context/weekly-measurement`. It opens that PR with + `GITHUB_TOKEN`, so no CI runs on the PR until a human closes and reopens it. GitHub's + merge button can't run the `context-counts` merge driver. If the PR shows a conflict, + re-run the workflow (`gh workflow run context-cadence.yml`), whose merge does run it. + It needs *Allow GitHub Actions to create and approve pull requests* (Settings → Actions → + General), on since 2026-11-17 by the operator's word. + ### Once, before the first deploy (the operator) 1. The root, root's alone: `sudo install -d -o root -g root -m 755 /srv/replicator`. @@ -265,7 +293,7 @@ including an empty namespace after a flush: `.github/dependabot.yml` proposes **action bumps only**, weekly. Every `uses:` in `ci.yml` pins a commit SHA with a `# vX.Y.Z` comment, and Dependabot moves both. `context-cadence.yml` is excluded, because the installer re-renders it (gregoryfoster/skills#373). `uv` stays parked under #169, until an org owner admits Dependabot to the co-pypi index (CannObserv/cannobserv#615). Guarded by `tests/ci/`. -A bot PR touches only `.github/`, so it needs **no deploy and no restart**. Merging it on GitHub puts `origin/main` ahead of this checkout: `git pull --ff-only` before the next local commit. If a bot PR is red at the WIF auth step, suspect the Dependabot run's OIDC token before the bump (the verdict table on #76). Read the action's release notes, not the diff: setup-uv v9 flipped `prune-cache` silently. A bump that changes behaviour takes fix commits pushed onto its branch. +A bot PR touches only `.github/`, so it needs **no deploy and no restart**. Merge it [like any PR](#main-takes-pull-requests-208), then `git pull --ff-only` before the next local commit. If a bot PR is red at the WIF auth step, suspect the Dependabot run's OIDC token before the bump (the verdict table on #76). Read the action's release notes, not the diff: setup-uv v9 flipped `prune-cache` silently. A bump that changes behaviour takes fix commits pushed onto its branch. ## Environment Variables diff --git a/docs/SKILLS.md b/docs/SKILLS.md index 57268f6..18356ba 100644 --- a/docs/SKILLS.md +++ b/docs/SKILLS.md @@ -246,8 +246,8 @@ git submodule update --init --recursive # The reviewing-* / shipping-* skills invoke this as a Phase 1 preflight. bash .skills/doctor.sh -# Pull upstream skill changes and bump the pointers. -# Normally unnecessary — the SessionStart hook below does this once per UTC day on main. +# Pull upstream skill changes and bump the pointers, on a branch: main takes PRs (#208). +# Normally unnecessary — the SessionStart hook below proposes this once per UTC day. git submodule update --remote --merge git add skills-vendor/ && git commit -m "chore: update skill submodules" @@ -256,29 +256,37 @@ bash skills-vendor/gregoryfoster-skills/skills/managing-skills/scripts/install-r ``` A `SessionStart` hook (`.claude/hooks/skills-submodule-update.sh`) refreshes `skills-vendor/` at most -once per UTC day, on `main` only, auto-commits the pointer bump (and `.skills/doctor.sh` when it -changed — never `.skills/` wholesale, which holds operator config), and never blocks a session. It -also re-installs `.skills/doctor.sh` each session, ahead of both gates, so the doctor self-heals on -any branch if deleted. Logs to `.git/skills-update.log`. - -**It pushes the commit it makes, and rolls it back if the push fails** -([skills#293](https://github.com/gregoryfoster/skills/issues/293)); a commit it left unpushed is -retried at the next session start. Until then it committed and stopped, and while the service ran -the checkout (before #151) that commit stopped it starting: the main-checkout guard refused a `main` -carrying unpushed commits (#48) — #72 found `b29efcf` unpushed for a day. The service runs a release -now, so a stranded commit costs nothing but a `git push`. The harness can still kill the hook between -commit and push, so the state is rare rather than impossible. - -Cheap habit, worth having before a deploy (`scripts/deploy.sh` deploys only what is on `origin/main`): +once per UTC day, on `main` only, proposes the pointer bump (and `.skills/doctor.sh` when it +changed — never `.skills/` wholesale, which holds operator config) as a pull request, and never +blocks a session. It also re-installs `.skills/doctor.sh` each session, ahead of both gates, so the +doctor self-heals on any branch if deleted. Logs to `.git/skills-update.log`. + +**It never moves `main`** (#208: `.skills/merge_mode` is `pr`; managing-skills' +`references/auto-refresh-hook/pr-mode.md`). It keeps **one** PR open from `skills/submodule-refresh`, +which later sessions replace rather than append to. The commit is built with `git commit-tree`, so +pre-commit never runs on it: the PR's CI is the gate that the direct push lacked when it put a red +`main` up on 2026-10-30. + +- **The skills advance only when someone merges that PR.** Until then the main checkout stays on + `main`'s pointers. Merge it like any PR ([DEPLOYMENT.md](DEPLOYMENT.md#main-takes-pull-requests-208)), + then `git pull --ff-only`. Until the pull, the hook proposes nothing and tells you on stderr to pull. +- **What it needs:** `gh` on `PATH`, an upstream for `main`, and a token. It reads `GH_TOKEN` from the + repo `.env` as data and never exports it. The session-start doctor warns when none of its sources + would answer. A missing prerequisite or a refused push is reported once, on stderr, and never retried + that day. +- **Before #208** it committed straight to `main` and pushed + ([skills#293](https://github.com/gregoryfoster/skills/issues/293)). + +Cheap habit before a deploy (`scripts/deploy.sh` deploys only what is on `origin/main`): ```bash -git status -sb | head -1 # "## main...origin/main [ahead 1]" is the tell -git log --oneline origin/main..main -git push origin main # if the only thing ahead is the refresh commit +git status -sb | head -1 # want "## main...origin/main" +# [behind N]: a PR merged on GitHub and not yet pulled — git pull --ff-only +# [ahead N]: a local commit on main — it belongs on a branch, in a PR ``` -`git log --oneline -- skills-vendor/` names every refresh the hook has made; `.git/skills-update.log` -records what it did each day, including the commit it created. +`git log --oneline -- skills-vendor/` names every refresh that merged; `.git/skills-update.log` +records what the hook did each day. **The hook is a symlink into the submodule, not a copy** (`managing-skills` Step 1). That is what makes upstream fixes to the script arrive on the normal submodule refresh; a copy freezes at whatever