From 9426f0646f5b902b8ce9db4a80ea4c6a3509ad2c Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Tue, 17 Nov 2026 15:53:20 +0000 Subject: [PATCH 1/7] #208 chore: re-render context-cadence.yml to the vendored template The installed workflow was 114 lines behind install-cadence.sh at 063ba5d: its --check reported the drift report and the delta check STALE and exited 3 on main before this change. This is the direct render, byte for byte, so the pr render that follows is reviewable as its own delta. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/context-cadence.yml | 139 +++++++++++++++++++++----- 1 file changed, 114 insertions(+), 25 deletions(-) diff --git a/.github/workflows/context-cadence.yml b/.github/workflows/context-cadence.yml index f2cf17b..23f2ca8 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. # @@ -45,11 +46,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 +58,30 @@ jobs: - name: Heal vendored symlinks run: '[ ! -x .skills/doctor.sh ] || bash .skills/doctor.sh' + # 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 # 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 +93,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,10 +123,11 @@ 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 /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 Date: Tue, 17 Nov 2026 15:53:20 +0000 Subject: [PATCH 2/7] #208 chore: set shipping-work's merge mode to pr .skills/merge_mode says pr, so shipping-work, the skills refresh hook and the weekly cadence workflow open or update a PR instead of pushing to main. The workflow is install-cadence.sh's pr render. The installer reads the knob from the primary checkout, which has none until this merges, so it was rendered in a scratch clone of this branch with the knob committed. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/context-cadence.yml | 171 ++++++++++++++++++++++++++ .skills/merge_mode | 1 + 2 files changed, 172 insertions(+) create mode 100644 .skills/merge_mode diff --git a/.github/workflows/context-cadence.yml b/.github/workflows/context-cadence.yml index 23f2ca8..4ae2120 100644 --- a/.github/workflows/context-cadence.yml +++ b/.github/workflows/context-cadence.yml @@ -25,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 @@ -58,6 +61,36 @@ 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 @@ -83,6 +116,55 @@ jobs: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} 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. # @@ -131,6 +213,8 @@ jobs: --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" diff --git a/.skills/merge_mode b/.skills/merge_mode new file mode 100644 index 0000000..1be11a8 --- /dev/null +++ b/.skills/merge_mode @@ -0,0 +1 @@ +pr From 87ed9822f0101af5250bb9050da1afa5aea295cc Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Tue, 17 Nov 2026 15:54:35 +0000 Subject: [PATCH 3/7] #208 docs: main takes pull requests; the refresh hook and the cadence open PRs Co-Authored-By: Claude Opus 5.5 --- docs/DEPLOYMENT.md | 34 ++++++++++++++++++++++++++++--- docs/SKILLS.md | 50 +++++++++++++++++++++++++++------------------- 2 files changed, 60 insertions(+), 24 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 3a3bab8..813f2b2 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -54,8 +54,10 @@ is the release, then its own `"worker ready"` line naming the build. A failed verify switches back and restarts the old build. The restart counts toward `StartLimitBurst=8`, as a manual one always did. -**Not the weekly measurement commit.** `github-actions[bot]` pushes get no CI run, -so the core refuses them: deploy the commit under it. +**Not a measurement commit the bot pushed.** Until #208 the weekly cadence pushed its +row straight to `main` as `github-actions[bot]`, and a `GITHUB_TOKEN` push gets no CI +run, so the core refuses those commits: deploy the commit under it. Since #208 the row +reaches `main` through a PR, and the merge commit gets the push's CI run. **Only commits from #151's merge on are deployable.** An older commit's units name no `/srv/replicator/live`, and the core refuses it before switching anything. @@ -66,6 +68,32 @@ no spare. Each is ~259 MB, under 1% of the 30 GiB root (#204): two put root near 54%, against the patching run's 84.0% ceiling. `KEEP=0` was chosen at 20 GiB, by the design doc's *Disk* table. +### `main` takes pull requests (#208) + +`.skills/merge_mode` is `pr`. shipping-work pushes the branch and opens a PR, and the +merge happens on GitHub. The next "ship it" after the merge runs its post-merge pass: +`git pull --ff-only` in the main checkout, then the deploy, then the issues it held +open with `Refs #`. 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 the merge + commit, or the `main` commit before it. +- **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. + The cadence needs *Allow GitHub Actions to create and approve pull requests* (Settings → + Actions → General). The PAT can't read that setting. + ### 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 From 55efa2ec0ea72f28e95f6caee399e5a4ed0113f0 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Tue, 17 Nov 2026 16:41:17 +0000 Subject: [PATCH 4/7] =?UTF-8?q?#208=20docs:=20CR=201=20=E2=80=94=20the=20p?= =?UTF-8?q?ost-merge=20pass=20offers=20the=20deploy,=20it=20doesn't=20run?= =?UTF-8?q?=20it?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- docs/DEPLOYMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 813f2b2..7350932 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -72,8 +72,8 @@ the design doc's *Disk* table. `.skills/merge_mode` is `pr`. shipping-work pushes the branch and opens a PR, and the merge happens on GitHub. The next "ship it" after the merge runs its post-merge pass: -`git pull --ff-only` in the main checkout, then the deploy, then the issues it held -open with `Refs #`. Nothing *enforces* this yet: `main` has no +`git pull --ff-only` in the main checkout, then an offer to deploy (optional when no +shipped code changed), then the issues it held open with `Refs #`. 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 From 906cccf22853d84552c5d33fbd4c56be517eb4f8 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Tue, 17 Nov 2026 16:41:18 +0000 Subject: [PATCH 5/7] =?UTF-8?q?#208=20docs:=20CR=203=20=E2=80=94=20a=20rol?= =?UTF-8?q?lback=20names=20a=20merge=20commit;=20the=20one=20before=20can?= =?UTF-8?q?=20be=20the=20bot's?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- docs/DEPLOYMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 7350932..57e9eb5 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -81,8 +81,8 @@ ruleset, so a by-hand `git push origin main` still lands. 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 the merge - commit, or the `main` commit before it. + 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` From 8ed8fe0c079f340c30a01f2fe886ad4928f8850e Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Tue, 17 Nov 2026 16:41:18 +0000 Subject: [PATCH 6/7] =?UTF-8?q?#208=20chore:=20CR=204=20=E2=80=94=20the=20?= =?UTF-8?q?merge=5Fmode=20knob=20says=20why?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .skills/merge_mode | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.skills/merge_mode b/.skills/merge_mode index 1be11a8..8e9e957 100644 --- a/.skills/merge_mode +++ b/.skills/merge_mode @@ -1 +1,4 @@ +# Work lands on main through a pull request merged on GitHub (#208): docs/DEPLOYMENT.md +# "main takes pull requests". Read by shipping-work, using-git-worktrees, the skills refresh +# hook and context-cadence.yml. One word: pr or direct. pr From aa1bb8a9b3150885f802308b9f975ee296132641 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Tue, 17 Nov 2026 16:41:18 +0000 Subject: [PATCH 7/7] =?UTF-8?q?#208=20docs:=20CR=205=20=E2=80=94=20the=20A?= =?UTF-8?q?ctions=20PR=20setting=20is=20on,=20by=20the=20operator's=20word?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- docs/DEPLOYMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 57e9eb5..6c5120b 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -91,8 +91,8 @@ ruleset, so a by-hand `git push origin main` still lands. `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. - The cadence needs *Allow GitHub Actions to create and approve pull requests* (Settings → - Actions → General). The PAT can't read that setting. + 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)