Skip to content

Switch to shipping-work's pr merge mode (.skills/merge_mode) #208

Closed

Description

@gregoryfoster

What

Switch this repo to shipping-work's pr merge mode: .skills/merge_mode set to pr, so work reaches main only through a pull request merged on GitHub (gregoryfoster/skills#342, #560).

Why

Today the repo is in direct mode [measured 2026-11-17]: there is no .skills/merge_mode, and the repo has no rulesets. Three writers push to main without a PR:

  • shipping-work, which fast-forwards main and pushes it;
  • the daily skills refresh hook (.claude/hooks/skills-submodule-update.sh), which committed and pushed 85f8d7b straight to main at 08:43Z today. It has pushed a red main before (2026-10-30);
  • the weekly context-cadence workflow, which pushes its measurement row to main with GITHUB_TOKEN.

In pr mode, each of the three opens or updates a PR instead, and CI runs before anything lands.

Scope

  • Commit the knob.
  • Re-render .github/workflows/context-cadence.yml with install-cadence.sh.
  • Update the docs that describe direct pushes.

Out of scope: a GitHub ruleset that enforces PRs on main. That is a separate operator decision, made after this one lands; its hazards are in the pre-flight.

Done when

  • .skills/merge_mode reads pr on main, and merge-mode.sh prints pr from the main checkout.
  • install-cadence.sh --check exits 0: not STALE.
  • The refresh hook's prerequisites check clean. The session-start doctor prints no merge_mode pr token warning.
  • The docs no longer say any of the three writers pushes to main.
  • The default suite matches the baseline, ruff is clean, and CI is green by job.
  • The first PR-mode run of the hook and of the cadence workflow is either observed, or recorded on this issue as verification debt.

Child of #154.

Activity

  1. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    Pre-flight (coordinator, epic #154, 2026-11-17)

    Measured against origin/main at 85f8d7b, with skills-vendor at 063ba5d. CI passed on all four jobs at 85f8d7b. The default-suite baseline is 2062 passed, 1 skipped, measured at d549a06; the commit since changes only .skills/doctor.sh and the submodule pointer.

    Today's state [measured]

    • The knob: there is no .skills/merge_mode, so the mode is direct.
    • GitHub: rulesets and rules/branches/main are both []. The PAT gets a 403 on classic branch protection, but the hook's direct push at 08:43:02Z went through.
    • Merge settings: merge commit, squash and rebase merges are all allowed. delete_branch_on_merge is on, and auto-merge is off.
    • Remote: github-replicator:CannObserv/replicator.git, an SSH deploy-key alias.
    • .skills/deploy_command is set (setsid -w scripts/deploy.sh).

    Site 1: the knob

    • Add .skills/merge_mode containing pr, and commit it. Every reader takes it from the primary checkout. The cadence workflow reads the committed file at run time, so a pr that's untracked or only staged renders the PR path and then runs direct.
    • This issue's own ship runs direct. The knob isn't on main until it lands, and merge-mode.sh reads main's checkout. Either ship it the usual way, or open it as a PR and merge it on GitHub to rehearse the post-merge pass. Say which you chose.

    Site 2: .github/workflows/context-cadence.yml

    • What breaks: it is a direct render (contents: write, git push origin "HEAD:$BRANCH" at :146). Once the knob says pr, install-cadence.sh --check reports STALE and exits 3. Re-run the installer in the same change. The pr render adds pull-requests: write, a step that reads the knob, and a push to context/weekly-measurement that opens or updates one PR.
    • The doc check flags it: changing .skills/merge_mode counts as a hit while the cadence workflow is installed (skills#647).
    • What GitHub needs [stated by curating-context/references/cadence.md:321-335, not measured here]:
      • A repo setting: Settings → Actions → General → Allow GitHub Actions to create and approve pull requests. The PAT can't read it (403), so the operator checks it. If it's off, the branch is still pushed, the job fails naming the setting, and the row waits for the next run.
      • No CI on the bot's PR: a PR opened with GITHUB_TOKEN starts no pull_request CI. Closing and reopening it starts the checks.
      • Conflicts: GitHub's merge button can't run the context-counts merge driver. If the PR shows a conflict, run the workflow by hand.
    • Today's run won't be affected: the cron is 27 17 * * 2, so it runs today at 17:27Z. That run pushes direct either way.

    Site 3: the skills refresh hook (managing-skills/references/auto-refresh-hook/pr-mode.md)

    • What changes: in pr mode it never moves main. It keeps one PR from skills/submodule-refresh, which later sessions update. Its commit is built with git commit-tree, so pre-commit doesn't run; the PR's CI is the gate.
    • What it needs:
    • The operator's new chore: the skills no longer advance until someone merges the refresh PR. Say this in the docs.

    Site 4: deploy and closing, through shipping-work's post-merge pass

    • Refs, not Closes: with .skills/deploy_command set, an issue about what production runs gets Refs #<n>, and the post-merge pass closes it once the deploy exits 0.
    • The deploy runs from the main checkout, after git pull --ff-only. run-deploy-command.sh refuses unless HEAD is main and equals its upstream.
    • The CI gate: scripts/deploy.sh:373-390 finds CI by head_sha with event=push on main. A GitHub merge is a push by the user who merges, so CI runs on it [traced]. A rebase merge pushes several commits at once, and CI runs on the newest only, which is the commit the deploy builds. Deploying an earlier one is refused, with the remedy printed.
    • Merge method, my recommendation: merge commits. They keep each #<n> type: commit and its SHA, the ones CI ran on in the PR. A squash's title would need to follow the commit convention by hand. Record the method in the docs. Restricting the repo's allowed methods is an admin setting, so it's the operator's call.

    Site 5: docs that describe direct pushes [measured by git grep]

    • Update:
      • docs/SKILLS.md:258-280: "It pushes the commit it makes", and the "cheap habit" block ending git push origin main. Both are false in pr mode.
      • docs/DEPLOYMENT.md:268: "git pull --ff-only before the next local commit" after a bot PR. In pr mode that is the rule for every merge, not just Dependabot's.
    • Still true, leave them: AGENTS.md:80 ("Deploy merged main"), docs/DEPLOYMENT.md:32-33,157, docs/COMMANDS.md:412.
    • Optional: a one-line note that main takes PRs only, in AGENTS.md or DEPLOYMENT.md. AGENTS.md is under a token budget, so measure it before and after.
    • No test reads merge_mode [measured]. tests/test_doc_sensitive_paths.py and tests/test_doc_sections.py don't change.

    Out of scope: an enforcing ruleset (later, the operator's decision)

    If one follows [stated, GitHub's documented behaviour]:

    • What it would refuse: the deploy key's push to main, which is the hook's direct path, and any by-hand fast-forward push.
    • The cadence bot's PR: its required checks never report until a human closes and reopens it.
    • What it needs: decide bypass actors. Turn the knob on first: a ruleset without it freezes the refresh, with one rejected push a day.

    Constraints

    Done when

    The issue body's list. For the first live runs of the hook and the cadence workflow, record what you observed, or record each as verification debt with the date it's expected: the hook's at the next session after the merge, the cadence workflow's on 2026-11-24 at 17:27Z.

  2. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    Pre-flight review (implementer, 2026-11-17)

    Checked against origin/main at 85f8d7b, skills-vendor at 063ba5d. Most of the brief holds. Below are the corrections and gaps; anything not mentioned was confirmed.

    Confirmed [measured]

    • No .skills/merge_mode; merge-mode.sh prints direct. Rulesets: 0.
    • Merge settings as stated. delete_branch_on_merge is true and allow_auto_merge false.
    • context-cadence.yml:146 is the direct git push origin "HEAD:$BRANCH". deploy.sh:373-390 is the CI gate as described. ci.yml runs on push: [main] and on pull_request: [main].
    • The refresh hook's prerequisites, checked from the main checkout: gh is at /usr/local/bin/gh, main@{u} is origin/main, ssh -G github-replicator gives hostname github.com, and the repo .env sets GH_TOKEN. So the doctor's #576 check stays silent.
    • actions/permissions/workflow gets a 403 from the PAT, so the operator checks Allow GitHub Actions to create and approve pull requests.

    Correction 1: an installer run from the worktree renders direct (Site 2)

    install-cadence.sh reads the knob from the primary checkout (resolve_primary, install-cadence.sh:317-460). Here that is /home/exedev/replicator, which has no knob until this merges. Run in the worktree, the installer renders the direct workflow, byte-identical to what's there, so "re-run it in the same change" does nothing as the brief words it. shipping-work's doc check says the same thing from the other side: "re-render it after the merge (#647)".

    What I'll do: commit the knob on the branch, then run the installer in a scratch clone of that commit, whose primary is itself, and copy the render back. The knob and the pr render then land in one commit range, with no STALE window on main. I'll put no untracked knob in the main checkout, because that would switch every other session's shipping-work and refresh hook to pr before the merge.
    How to verify:

    • Before the merge, from the worktree: --check prints the direct, under a workflow rendered for pr note, which is informational and exits 0.
    • After the merge, from the main checkout: --check should print merge mode: pr and re-render: none and exit 0. That is the Done-when check, and it can only run after the merge.

    Correction 2: doc sites the brief missed (Site 5)

    • docs/DEPLOYMENT.md:57: "Not the weekly measurement commit. github-actions[bot] pushes get no CI run". In pr mode the bot pushes only to context/weekly-measurement. The row reaches main when a human merges the PR, and that merge commit does get a push CI run. The refusal still applies to the bot's older direct commits, so the paragraph needs rewording, not deleting.
    • docs/SKILLS.md:248-262: "does this once per UTC day on main" and "auto-commits the pointer bump" describe the direct path. So does the manual-refresh block, git add skills-vendor/ && git commit … on main. In pr mode a hand refresh also goes on a branch and through a PR.
    • docs/SKILLS.md:160: "the refresh hook and the weekly context-cadence job commit into .skills/" is still true, since they now commit through their PRs. I'm leaving it.

    Correction 3: merge commits, in more detail (Site 4)

    • The merge commit's title: the repo's merge_commit_title is MERGE_MESSAGE, so the commit on main reads Merge pull request #N from CannObserv/<branch>, not #<n> type:. Nothing here enforces the commit convention: pre-commit runs only ruff, and no commit-msg hook exists. The #<n> type: commits survive inside the merge. I'll document this; it is not a blocker.
    • "The SHAs CI ran on in the PR" is loose: pull_request CI runs on GitHub's synthetic refs/pull/N/merge, not on the branch's commits. The commit the deploy builds is the merge commit, and the push to main gives it its own CI run.
    • Rollback targets become merge commits: a #<n> commit inside a merged PR has no push CI run of its own, so deploy.sh <sha12> refuses it with the message from :384. This is the same kind of limit as today, where a multi-commit fast-forward push runs CI on its tip only. It needs saying in DEPLOYMENT.md's rollback guidance.

    Plan

    • One commit range on 208-pr-merge-mode: the knob, the re-render, and the docs. The note that main takes PRs only goes in DEPLOYMENT.md, not AGENTS.md, because shipping-work and the hook read the knob themselves and AGENTS.md is under a budget.
    • I'll push the branch and open a draft PR (Refs #208) so CI reports by job. Merging, or shipping it direct, is the operator's call; I'll pause there.
  3. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    Operator decisions and post-merge host steps (PR #209)

    PR #209 is a draft, waiting for the operator. Nothing has merged or deployed.

    Before merging: the operator's decisions

    1. How #208 Switch to shipping-work's pr merge mode #209 lands. Its own ship runs direct, because merge-mode.sh reads main's checkout, which has no knob yet. Either:
      • (a) Merge it on GitHub with a merge commit (my recommendation). This rehearses the post-merge pass and puts the first merge commit on main. Or:
      • (b) Ship it direct. That fast-forwards main and marks #208 Switch to shipping-work's pr merge mode #209 merged.
    2. The merge method. DEPLOYMENT.md's new section records merge commits, the pre-flight's recommendation. If you choose another, say so and I'll change the doc. Narrowing the repo's allowed methods (all three are on today) is an admin setting.
    3. Check the setting Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests. The PAT gets a 403 on actions/permissions/workflow, so I could not read it.
    4. Today's 17:27Z cadence run: timing matters. A scheduled run uses the workflow file on main when it fires, and checks out main, knob included.
      • Merged before ~17:27Z: today's run is the first pr-mode cadence run. If the setting is off, the job goes red after pushing context/weekly-measurement. The row waits on that branch and the next run keeps it.
      • Merged after the run finishes: today's run pushes directly with the old render. That is harmless, but run git pull --ff-only afterwards, because the bot will have moved main.

    After the merge, from /home/exedev/replicator (the main checkout)

    git switch main && git pull --ff-only           # (a) only; (b) is already there
    bash .claude/skills/using-git-worktrees/scripts/merge-mode.sh                # want: pr
    bash .claude/skills/curating-context/scripts/install-cadence.sh --check; echo $?
    #   want: "merge mode: pr (one standing PR …)", "re-render: none", exit 0
    bash .skills/doctor.sh                           # want: no "merge_mode is pr" token warning
    uv sync --frozen                                 # dev venv only: points the editable install back at main
    bash .claude/skills/using-git-worktrees/scripts/worktree-destroy.sh 208-pr-merge-mode --force

    First live pr-mode runs (verification debt until observed)

    • The refresh hook: it already ran today, at 08:43Z, directly. Its next run is the first session start on 2026-11-18 UTC. Check .git/skills-update.log for its pr-mode path. With no upstream skills change it proposes nothing, which proves only that the prerequisites passed; the first actual PR comes with the first upstream change.
    • The cadence: today at 17:27Z if merged before then, otherwise 2026-11-24 at 17:27Z. Expect:
      • a PR from context/weekly-measurement, titled chore: weekly context measurement;
      • no CI on it, until a human closes and reopens it;
      • merged with a merge commit, then git pull --ff-only.

    Coordinator

    • Update the memory on fast-forward pushes closing a PR's issue. In pr mode the merge on GitHub closes Closes #N. With .skills/deploy_command set, shipping-work uses Refs.
  4. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    Operator, 2026-11-17: Allow GitHub Actions to create and approve pull requests is enabled for this repo (decision 3 in the host-steps comment). The cadence's gh pr create is no longer blocked by that setting. It can't be verified from here (the PAT gets a 403), so it is recorded as the operator stated it.

  5. added 3 commits that reference this issue on Nov 17, 2026
  6. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    CR 1 (with --fix applied), PR #209

    Four findings were applied, one commit each:

    • CR 1, 55efa2e: the post-merge pass offers the deploy; it doesn't always run it.
    • CR 3, 906cccf: a rollback names a merge commit. The commit before one can be a cadence-bot commit from the direct-push era, which has no CI run.
    • CR 4, 8ed8fe0: .skills/merge_mode gets a comment line saying why. A clone of the branch still reads pr, and the re-render is unchanged.
    • CR 5, aa1bb8a: the Actions PR setting is recorded as on, as the operator confirmed.

    The gate after the fixes: 2062 passed, 1 skipped, and ruff check and format are clean.

    Held for the operator

    • CR 2, the merge method. DEPLOYMENT.md says "merge with a merge commit" (the pre-flight's recommendation). The cohort disagrees:

      • processor (docs/SKILLS.md § Merging under pr, init-socraticode: drop the health hook's hand-rolled cap wrapper once the vendored skills include #330 #115) never uses GitHub's button. Once CI is green on the PR head, it runs git merge --ff-only origin/<branch> && git push origin main from the main checkout. Its reasons: a rebase merge rewrites SHAs, so the SHA CI tested isn't the one that ships, and a squash loses the CR N commits. A merge commit avoids both, but adds a Merge pull request #N commit. A fast-forward push also stops working the day a PR-only ruleset arrives.
      • archiver and cannobserv merge on GitHub.

      Tell me which method to use and I'll align DEPLOYMENT.md (the :60 sentence and the merge bullet).

    • CR 6, the actions/checkout@v7 pin. It's a floating tag in context-cadence.yml. ci.yml pins a SHA, as processor's and watcher's cadence files do, and a re-render keeps an installed SHA pin (skills#373). The trade-off: the job holds contents: write, pull-requests: write and ANTHROPIC_API_KEY, but Dependabot excludes this file, so a SHA pin would only ever be bumped by hand. This predates Switch to shipping-work's pr merge mode (.skills/merge_mode) #208, which had @v5.

  7. added a commit that references this issue on Nov 17, 2026
  8. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    Merged and checked (2026-11-17)

    PR #209 was merged on GitHub with a merge commit, a072ba5 at 17:11:50Z, by the operator's decision.

    • Merge method (CR 2): merge commits, as DEPLOYMENT.md's "main takes pull requests" section already says. No doc change needed.
    • Merge commit's CI: run 44134290195, a push event on a072ba5, passed all four jobs (lint, test, browser, gcs). That confirms the pre-flight's traced Site 4 claim: a GitHub merge is a push that gets CI, so deploy.sh can build it.

    Done when

    Item Result
    .skills/merge_mode reads pr on main, and merge-mode.sh prints pr from the main checkout ✅ prints pr, exit 0
    install-cadence.sh --check exits 0, not STALE ✅ exit 0: merge mode: pr, re-render: none, every guarantee yes
    Hook prerequisites clean; no doctor token warning ✅ gh on PATH, main@{u} = origin/main, ssh -G → github.com, GH_TOKEN in .env. The doctor exits 0 with no merge_mode or token line.
    Docs no longer say the three writers push to main ✅ docs/SKILLS.md and docs/DEPLOYMENT.md (87ed982, plus CR fixes 55efa2e, 906cccf, aa1bb8a)
    Suite matches the baseline, ruff clean, CI green by job ✅ 2062 passed, 1 skipped; ruff check and format clean; four of four jobs green on the PR head aa1bb8a and on a072ba5
    First PR-mode runs observed or recorded as debt ⏳ debt, below

    Verification debt

    • The cadence workflow. Its first pr-mode run is today. The cron says 17:27Z, but recent scheduled runs started between 20:44Z and 22:26Z, so expect it around 21:00–22:30Z. Expect a PR from context/weekly-measurement titled chore: weekly context measurement. No CI runs on it until it is closed and reopened. Merge it with a merge commit, then git pull --ff-only. If it's not observed, the next chance is 2026-11-24.
    • The refresh hook. Its first pr-mode run is the first session on 2026-11-18 UTC: today's ran at 08:43Z, directly, using the hook from before #647. Look for a pr-mode line in .git/skills-update.log. With no upstream skills change it proposes nothing, which proves only that the prerequisites pass. The first real PR comes with the next upstream change.

    Not done, by choice

    • No deploy. #208 Switch to shipping-work's pr merge mode #209 changes no worker code, so the operator left it out. A future deploy of a merge commit will exercise deploy.sh's CI gate on one for the first time; this run already proves the CI half.
    • CR 6 (a SHA pin for actions/checkout in context-cadence.yml) is still the operator's call.

    Filed

    For #154

    • Memory update: shipping-work now runs pr mode here. A GitHub merge closes Closes #N; with .skills/deploy_command set, shipping-work writes Refs. The memory about a fast-forward push closing the PR's issue only describes the old direct flow.
    • New operator chore: merge the refresh hook's standing PR from skills/submodule-refresh, or the vendored skills stop advancing. Archiver's PR #515 has been open since 2026-11-16.

    Cleanup: the main checkout is on a072ba5, the dev venv points back at main (uv sync --frozen), and the worktree and local branch are removed.

    Closing: every Done-when item is met or recorded above as debt.

  9. gregoryfoster commented on Nov 17, 2026

    @gregoryfoster
    MemberAuthor

    Verified (coordinator, epic #154, 2026-11-17T17:3xZ)

    I read all of this in this check-in [measured]:

    • Range: 85f8d7b..a072ba5: 7 commits (9426f06 through aa1bb8a), merged by PR #208 Switch to shipping-work's pr merge mode #209 with a merge commit, a072ba5, at 17:11:50Z. Its parents are 85f8d7b and aa1bb8a. The diff touches context-cadence.yml, .skills/merge_mode, docs/DEPLOYMENT.md and docs/SKILLS.md, and no worker code.
    • CI by job: lint, test, gcs and browser passed on a072ba5, in a push run (44134290195), and on the PR head aa1bb8a. So a merge made on GitHub gets the push-event CI run deploy.sh's gate needs. That was the pre-flight's traced Site 4 claim; it is now measured.
    • The knob: .skills/merge_mode is pr plus three comment lines, and merge-mode.sh prints pr from the main checkout (exit 0).
    • The cadence render: install-cadence.sh --check exits 0, with merge mode: pr (one standing PR from context/weekly-measurement) and re-render: none.
    • The doctor: .skills/doctor.sh exits 0, with no merge_mode or token line.
    • Docs:
      • git grep finds "pushes the commit it makes" nowhere.
      • The one git push origin main left is DEPLOYMENT.md:77, which correctly says that, with no ruleset, a push by hand still lands.
    • Suites on a072ba5, run by me in the foreground:
      • Default suite: 2062 passed, 1 skipped, in both a clean and a loaded shell. The skip is the known test_co_core_closure_diff.py:433.
      • tests/ci: 44 passed.
      • ruff check, ruff format --check and uv lock --check are all clean.
    • Live: still 59fb24082f7e, pid 39128, NRestarts=0. Not deployed, by the operator's choice; live trails main by text and workflow only.
    • Cleanup: the main checkout is on main at a072ba5 and clean. One worktree is left, and no 208* branch.
    • Filed upstream, and both exist:

    Carried to the epic:

    • Verification debt:
      • the first pr-mode cadence run, expected today around 21:00–22:30Z, or else 2026-11-24;
      • the refresh hook's first pr-mode run, at the first session on 2026-11-18.
    • Watching: the standing PRs from skills/submodule-refresh and context/weekly-measurement, which an operator merges, with merge commits.
    • Still the operator's: CR 6, a SHA pin for actions/checkout@v7 in context-cadence.yml.
    • The coordinator's memory now describes pr mode.

    Nothing is owed.

  10. added a commit that references this issue on Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions