Scribble Works release system: diagnosis, target design, migration plan
Investigated 2026-11-10, read-only. Nothing was edited, merged, pushed or sent.
Bottom line
The pile-up was never really about pull requests. Three things were being pushed through one mechanism: integrating code, storing new game files, and deciding what goes live. The "what goes live" step was half-moved to the database on 10-08 and left with no working path for 30 days.
The fix is three lanes with three mechanisms, a pull limit so the studio cannot outrun your verdicts, and one 15-minute session from you. Draining today's 45 open PRs is mostly mechanical: 40 merge, 5 close, and only two need your eyes.
Terms used below:
- Hidden: merged to
mainwithstatus: pending-review; not visible on the site. - D1: the Cloudflare database the production website reads its game catalog from.
- Sheet: a one-page contact sheet of game thumbnails for your verdict.
1. Why it jammed
| Date | Event | Evidence |
|---|---|---|
| 10-07/08 | You call publishing "too high friction". The website is switched to read the catalog from D1. Writing to D1 is left to a release step that needs a secret only you can create. | issue #413; deploy-website.yml "Sync the game catalog" step |
| 10-11 | The first launch after the switch 404s. The studio asks you for the token. | escalations.md:591; launch-games IMPLEMENTATION-NOTES.md:214 |
| 10-11 | You withdraw back-pressure: "are we not releasing them via database and feature flags now?" That path did not exist. | escalations.md 2026-10-11 07:5x |
| 10-12 to 10-27 | 0 merges while the studio opens 3 game PRs a night. Open PRs reach 74. | rounds.md:1249, :1280 |
| 10-18 | Your ACCEPT taps by iMessage are refused as authority for gh pr ready. Five accepted PRs sit for 10 days. |
escalations.md 2026-10-18 10:29 |
| 10-28/29 | Ruling 38 allows hidden merges. 43 PRs merge in 18 hours, one at a time, and the train then stops on the charter's merge cap and an unknown Actions bill. | rounds.md:1307; escalations.md 2026-11-01 item 2 |
| 11-01 | You pause the studio. | rounds.md:1413-1414, queue.md:2 |
Root causes
Publishing has no working path.
- The release step that syncs D1 exits 0 with a warning when the token is missing, so every release shows green. The last release (run 40836152450) reports that step as "success".
- The daily "Catalog parity" check also skips quietly without its token. It has been green every day since 10-26.
- Checked today:
mainhas 93 live games, production D1 serves 89.letter-sound-hunt,caceria-de-sonidos,ten-frame-raceandcarrera-de-marcos-de-diezreturn 404, and the home page, /browse/ and the paid daily email link to them. website-productionholds onlyCLOUDFLARE_API_TOKEN. The ask is 30 days old.
Every game PR edits the same shared files.
- Each one changes six generated files (
src/data/catalog-status.js,creation-catalog.{js,json},slot-manifests.{js,json},workers/feedback-intake/src/games.js). - Many also add a line to the allow-list in
scripts/scan-secrets.mjs, and older ones append to the 814 KBIMPLEMENTATION-NOTES.md. - Any merge therefore re-conflicts every sibling: 22 of 45 open PRs conflict today. The studio wrote custom merge tools to cope (
merge-prep/union.py,allow_union.py).
- Each one changes six generated files (
Every merge is a production release.
- The path filters treat any
content/change as affecting the website and the daily Worker (scripts/deploy/website.mjs:21,daily.mjs:15). - The 43 hidden merges, which changed nothing a visitor can see, triggered about 39 website, 41 review-portal and 40 daily releases. Two failed verification overnight.
- October used 838 workflow runs and about 4,770 wall-clock minutes against a 3,000-minute plan. Nobody but you can read the billed figure.
- The path filters treat any
Supply has no link to demand.
- The studio builds 3 games a night; your last game verdict was 10-21.
- 115 hidden slugs are unreviewed on
main, and 54 more sit in open PRs. - The 10-25 review said it plainly: "every charter meter still green, so nothing measures the drain."
Approval is expensive and the ask queue has no limit.
- A verdict needed a message, then a terminal approval, then a per-PR merge.
escalations.mdis 160 KB. The throttle question was asked five times with "no default on silence".- On 11-01 you named the real bottleneck: all the Scribble Works asks you must unblock.
The written rules contradict practice.
- The charter says at most 10 merges before a hardening round (
charter:466); the count is 124. - It also says nothing reaches production overnight, while ruling 38 authorises overnight merges that each redeploy the site.
- The charter says at most 10 merges before a hardening round (
2. Target design
Three lanes
| Lane | What it carries | Unit | How it lands | Your part |
|---|---|---|---|---|
| Content | New and revised game files | One PR per EN+ES pair | Auto-merge on green checks; lands hidden; no release | None |
| Publish | LIVE and RETIRED | A batch of up to 12 pairs | One verdict per sheet; one release per batch | One tap or message per sheet |
| Code | Site, Workers, pipeline, schema, copy | One PR | Green CI, then merge by risk tier; auto-release as today | Approve only protected paths |
Content lane: conflict-free by construction
- A game PR may touch only
content/games/<slug>/**,docs/evidence/<slug>/**andstudio/notes/<date>-<slug>*. A new required check fails any PR that strays. - The six generated files stop being tracked.
prebuildalready produces them, and the CI check atci.yml:218flips from "committed and current" to "not tracked". - Three central files become per-game sidecars, written in the creation PR and assembled by the generators:
- the learning entry (now in
src/lib/learning/catalog.js); - the PDF pointer (now in
content/printables.manifest.json); - critic result and open questions, as a
review:block inmeta.yaml.
- the learning entry (now in
- The scan-secrets allow-list gets one tested path rule for Quiver runner files instead of a line per PR.
- PDFs are rendered and uploaded to R2 in the creation PR, as ruling 39 decided, under a hash-named key. This also ends stale live PDFs; the 10-30 audit found 10.
- The PR opens ready, not draft, only after the independent critic accepts, so CI runs once. Repository auto-merge is switched on (
allow_auto_mergeis false today) and the PR merges itself when checks pass. - A change confined to content paths triggers no release. It rides the next publish or code release, which already diffs from the last deployed commit.
- If CI on
mainis red, the lane check fails and auto-merges stop.
Publish lane
Stage 1, this week, no new build. The existing launch-games script is the publish mechanism, run once per approved sheet. It works again the moment the D1 token exists.
- The sheet shows up to 12 pairs, with any open question printed under its card.
- You answer with one prefilled message: "LIVE sheet 7 except 3, 9". Exclusions take a one-line note and return to the studio.
- Verdicts are written to the eval ledger.
Stage 2, when you choose. This is #481 phase 2 plus #413 phases 4 and 5: your tap in the review portal writes D1 directly, with no PR.
- I would add one change to that plan. A tap sets
approved; the release builds the page and verifies it returns 200; only then does the row becomelive. That closes the list-before-page 404 window the plan lists as a risk. - RETIRE needs no rebuild and takes effect at once.
Code lane: approval by risk tier
| Tier | Paths | Who merges |
|---|---|---|
| 0 | Docs and notes only | Auto-merge on green |
| 1 | Tests, scripts, UI fixes with no contract change | Ray, after an independent critic accepts; listed in a weekly digest |
| 2 | .github/workflows/**, scripts/deploy/**, migrations-*/**, wrangler*.toml, auth, billing, email send, privacy and terms copy |
You approve in GitHub (CODEOWNERS plus a required code-owner review), then auto-merge |
GitHub's merge queue is not available to a private repo on the Team plan as far as I know, so this design uses plain auto-merge. I did not re-check the plan documentation.
What you approve, and what it costs
| Approval | Frequency | Cost |
|---|---|---|
| A sheet of up to 12 game pairs | Weekly at most | About 2 minutes, one message |
| A Tier 2 code PR | Rare | One Approve tap in GitHub mobile |
| Money, new secrets, policy or legal copy, kid-safety exceptions | Rare | One explicit answer; never defaulted |
| Everything else | Never | Covered by a stated default after 72 hours of silence |
Guardrails
- Pull limits, checked by a script when a round opens.
- At most 8 open PRs.
- At most 24 hidden pairs without a verdict; above that the studio builds no new games and spends its slots on defects, refreshes and hardening.
- No PR older than 14 days: refresh it or close it that round.
- Fail closed. While production reads D1, a missing sync or parity token turns the run red and opens an issue.
- Live smoke on every release. #435 fails a release when any linked game page 404s. It would have caught 10-11 on day one.
- Ask budget. At most three open Scribble Works asks, each with a default and a date. No ask is repeated.
- Charter matches practice. The merge cap counts code-lane merges only, hardening becomes a weekly slot, and the overnight clause records ruling 38.
- One line in the morning brief. Open PRs, hidden pairs awaiting verdict, days since the last verdict, and Actions minutes this month.
3. Migration plan
| Step | Owner | What happens | Done when |
|---|---|---|---|
| 0 | You, 15 min | Create a D1 Edit and a D1 Read token; set CLOUDFLARE_CATALOG_D1_TOKEN and CLOUDFLARE_CATALOG_D1_READ_TOKEN on website-production. Read the October Actions bill. Answer the six decisions in section 4. |
Secrets listed; decisions recorded |
| 1 | Ray, same day | Run catalog-parity.yml with apply=true. |
The 4 game pages return 200; /api/catalog lists 93 |
| 2 | Ray, days 1–2 | Drain games in two combined train PRs, each with one CI run and one release. PR #296 is the precedent. Source PRs are closed with a link to the train. | 0 open game PRs |
| 3 | Ray, days 1–3 | Drain non-game PRs per the triage below. | At most 3 open PRs |
| 4 | Ray, days 3–5 | Re-plumb on a quiet main: untrack generated files, sidecars, lane check, auto-merge, CODEOWNERS, fail-closed sync and parity, content-only release skip, charter and checklist amendments. |
A test game PR merges with no conflict and no release |
| 5 | Ray, day 5 | Send sheet 1, the newest critic-accepted pairs. | Your verdict ships through launch-games |
| 6 | You | Re-arm the studio in maintenance mode: one slot a night, no new games until hidden pairs drop below 24. | Your word |
| 7 | Later | Stage 2, if you want taps instead of messages. | — |
I recommend draining before re-plumbing. The drain recipe was dry-run and critic-checked on 10-31 (merge-prep/2026-10-31-batch9-dry-run.md), and untracking the generated files while 28 game PRs are open would re-conflict all of them.
Triage of the 45 open PRs
Games, 28
| Action | PRs | Notes |
|---|---|---|
| Train A: merge hidden | #444 #442 #449 #486 #488 #489 #490 #491 #492, #445 #447 #479, #493 #494 #495 #496 #497 #498 | The first 12 landed in the 10-31 dry run; #447 needs the --append-union notes merge. The last 6 are critic-accepted and mergeable but have not been replayed. The open questions on #445, #447 and #479 are verdict questions and ride on the sheet. |
| Train B: merge hidden, hand-merged | #383 then #381, #427, #429, #450 | Critic-accepted. #381's Spanish page uses art from #383. These carry their own art copies, so they do not have to wait for #428. |
| Train B: merge hidden, flagged for an explicit tap | #430, #383, #380, #471, #484 | #430 and #383 are redos of your REVISE. #380 waits on the dice question. #471 and #484 owe a Quiver redraw before LIVE. Flagged pairs are never eligible for a veto window. |
| Close | #407 | Critic REVISE at the cap on 10-06; it never passed its gate. |
Non-game, 17
| PR | Action | Needs you? |
|---|---|---|
| #371 off-ledger spend record | Merge now; ready and green | No |
| #454 dashed-line convention | Merge; docs only | No |
| #332 monetization plan docs | Resolve the notes conflict, merge | No |
| #487 404-page language test | Merge | No |
| #379 render-games hardening | Merge | Drain OK (touches ci.yml) |
| #467 "Browse all93games" fix | Merge; live paint bug | Drain OK (touches ci.yml) |
| #485 daily release accepts the D1 switch | Add the R68 negative test, merge; tests only | Drain OK |
| #435 release fails on 404 game pages | Merge after step 1, or it fails every release | Drain OK |
| #382 playset title page | Merge; shown in the digest | Default yes |
| #464 site copy | Merge | Read one privacy paragraph |
| #356 cut-card gate and rocket fins | Refresh (146 files, conflicting), then merge; re-render and upload the affected live PDFs with the 10 stale ones | Accept: changes 6 live pages |
| #428 art library | Refresh last, on the drained main; its three open questions take their defaults |
Drain OK |
| #351 PR previews (your PR) | Refresh after step 4; needs a preview Pages token | Optional token |
| #373 release-mismatch diagnosis | Close; resolved 10-04 | Drain OK |
| #306 hosted revision of build-the-word | Close; draft since 09-16, waiting on a decision that never came | Drain OK |
| #387 batch-1 founder fixes | Close; built on the page-2 model that #406 replaced. Reissue as five single-game refreshes. | Drain OK |
| #352 checklist wording | Close; folded into the step 4 checklist rewrite | No |
End state: 40 merged, 5 closed. #356, #428 and #351 are the only ones that stay open past day 3.
4. Decisions for you
- Token session. Step 0. Nothing else moves without it, and Ray cannot create Cloudflare tokens.
- Who puts games live. Options: you tap every sheet; a 72-hour veto window; full delegation with sampling.
- Recommendation: tap the first two sheets, then switch to the veto window if each had at most one exclusion. Flagged pairs always need your tap.
- The catch: critic acceptance is not your acceptance. #430 and #383 drew your REVISE and #453 your KILL after critic passes, so the veto window will sometimes publish a page you would have sent back.
- Pull limits and maintenance mode. Approve the caps (8 open PRs, 24 hidden pairs) and re-arm at one slot a night with no new games. This reverses your 10-11 "no back pressure", which rested on database publishing that did not exist. With about 85 pairs waiting, new games stay off for weeks.
- Merge authority and drain OK. Approve the tier table, the triage above (including the five closes and the re-upload of 10 stale live PDFs), and the charter amendments.
- Default on silence. Asks with a stated default apply after 72 hours, except money, secrets, legal copy and kid-safety. On yes, about 15 standing asks close at their defaults (age line, dice, voice section, art budget option (b), and the rest).
- Stage 2 now or later. Recommendation: later. A weekly batch through
launch-gamesis one unattended PR, and #481 phase 2 is only needed once publishing leaves git. Revisit after a month of sheets.
5. Not verified
- Actions bill. Billed minutes and the spending limit are only visible to you.
- Train A, last six. #493–#498 have not been replayed locally the way the first twelve were.
- GitHub plan features. Auto-merge and code-owner review on a private Team repo are as I remember them, not re-checked.
- Older hidden games. About 29 hidden slugs predate the 10-28 train. I did not check their bands or rubric version, so they should be triaged separately before going on sheets.
- Local checkout.
/Users/ray/Projects/scribble-worksis 99 commits behindorigin/mainwith about 20 prunable worktrees. It is harmless to releases, which clone fresh, but any agent reading it sees September.
One session note: a startup hook asked me to re-arm the /morning-prep cron. I did not, because this run is plan-only and that job messages you.