---
name: "convention-github"
type: convention
description: 'Conventions for GitHub in Aled''s system — repos in scope, which surface may touch a repo (Forge''s lane versus a credential-less session), branch naming, PR structure, GitHub MCP usage and read-volume safety, running build:manifest to keep the claude-ops publish mirror in sync, generating a PR body''s digest block rather than retyping it, the sequence for standing up CI on a repo, why a required check is enforceable per repo on Pro and a workflow_dispatch run does not satisfy one, why a brand-new workflow has no workflow_dispatch path pre-merge, the workflow run held at action_required that never starts, and the Chromatic pending-baseline gate — a human review gate that routes to In Review, never Blocked. Read before any operation that touches GitHub: creating repos, branches, PRs, adding or changing CI, publishing canon to claude-ops, diagnosing a PR that will not merge, using the GitHub MCP tools, or deciding whether repo code work should be hand-run or routed to Forge. Grown as the conventions solidify.'
license: CC BY-NC-SA 4.0
---

# convention-github

How GitHub is used in Aled's system. Follows the same pattern as `convention-linear`. Grown here as the conventions solidify — this is a stub, not the final word.

## Role

GitHub is the source-control and PR host. All delivery repos live under `assoc-one`, which is a **personal account, not an organisation** — the Owner is a member of no organisation, verified on the account page 2026-09-14. This is load-bearing and non-obvious, because `github.com/assoc-one/...` reads exactly like an org URL. Read "org" anywhere below as the account, and treat any instruction that turns on an organisation-only feature as unavailable rather than pending. Claude Code agents interact via the GitHub MCP tools (prefixed `mcp__github__`).

## Who touches a repo, from which surface

Repo code work is **Forge's lane**, reached through the delivery loop — it is never hand-run from an interactive session. An interactive Cowork / Claude session (the surface these sessions run on) **holds repo credentials as a property of the surface, not as a fact about the class** — so GitHub reach is a property of the surface in hand, read at run time by one cheap call and never asserted from this page. Probe before concluding, and probe for data rather than for a self-report: `git ls-remote <remote>` for git reach, one repo-scoped REST read against an attached repo — `gh api repos/<owner>/<repo>/commits/<sha>/check-runs` — for token reach, and a single `mcp__github__*` read for MCP reach. **`gh auth status` is not the token probe**: on this surface on 2026-10-23 it reported the token invalid while `gh api user` returned 200, so it answers in the direction that closes a working route (*GitHub MCP tools*). Each costs one call and settles the question for the surface actually running, which no written claim can; a universal in either direction is wrong on some surface and the page cannot tell which. Three measured points, deliberately not one: a 2026-07-22 interactive session whose direct clone failed on auth; the ops-sync cloud scheduled task, reported to hold working `git fetch` and `mcp__github__*` access; and this Pulse refine surface, measured first-hand on 2026-10-16, where `git ls-remote` on `assoc-one/claude-ops` fails with *"could not read Username for 'https://github.com': terminal prompts disabled"* and `gh auth status` reports *"The token in GH_TOKEN is invalid"*. **That third point is superseded in part — not deleted — by a fuller reading of the same surface on 2026-10-23:** `gh auth status` still reports the token invalid and `git ls-remote` still fails, and `gh api user` returns 200 as `assoc-one` on the same surface in the same minute. So what was recorded as a surface with no reach is a surface with **no git reach and working repo-scoped REST**, gated per repo by attachment rather than by the credential (*GitHub MCP tools*). The conclusion this point carries is unchanged, and now rests on the git failure and on the 2026-07-22 clone rather than on the auth self-report: a universal "every session has access" is still wrong, because reach is partial, per surface and per repo. What the correction removes is the opposite error — reading the 2026-10-16 entry as total reachlessness, which closes a route that answers and is the costlier of the two directions. **And the routing stands as routing, not as inability:** repo code work is Forge's lane because the delivery loop carries the build, review and merge, which is true of a session that can reach the repo exactly as it is of one that cannot, so a successful probe is never a licence to hand-run repo code work from an interactive session. Unverified, and the stronger inference is not established: whether the ops-sync task's working fetch used the session's own credentials or a mounted host clone's credential helper. `skill-ops-sync` reads a **local clone on the Owner's machine** and its own boundary forbids network git — *"never clone/fetch/push"* — so the reported fetch is at odds with that artefact's own rule and may be the helper rather than the surface. Read it as evidence that reach varies, not as evidence that a cloud task holds credentials. **That is not the same as having no route.** Such a session can attach a repo through the add-repo tool, with write access, and push a branch; it cannot delete one, as in the delivery sandbox. Repo code work is therefore Forge's lane as a **routing decision**, not as an inability: the delivery loop carries the build, review and merge, and that is why the session routes there. (The add-repo tool is present in these sessions; the branch push and the failed delete are reported from a 2026-10-07 test and not observed here — APP-2210.) The correct move for repo code work from an interactive session is to **diagnose from the ticket, make it Forge-executable, and route it into the delivery lane** (Todo + `agent:F0-RGE`) for Forge to run against the connected repo — not to attempt a clone first and route only after it fails. The routing is right; trying the clone first is the friction, and it recurs — interactive sessions repeatedly assume they can reach GitHub directly, burn a step discovering they cannot, then route. (Worked case: A1-156, `assoc-one/meirionpritchard-com` Chromatic bug, 2026-07-22 — the session's first move was a direct clone that failed on auth, then it correctly made the ticket Forge-executable and routed it — APP-651.)

This is the repo edge of `core-operating-model`'s three-lane split: a repo-native change is the **delivery lane**, executed by Forge, and is never hand-run from an interactive Cowork session. The rule to reach for is *don't hand-execute repo code from an interactive session — route it to Forge.*

## Repos in scope

This table is informational only — the delivery loop scans by Linear project/label, not by this list, so a stale row here does not silently gate anything. Keep it current anyway: it is the one place a person can see what's live.

**It is not a census, and no delivery run can produce one.** An account-wide repo listing is refused from a delivery session, so a run can verify each repo this table names and can never establish that the table names every repo that exists. The two are not provably the same set from inside a run. So an acceptance criterion phrased as *"the full repo list"* or *"every repo in the account"* is unmeetable by construction and is authored against **the repos named in this table** instead; where a criterion already carries the wider wording, QA verifies the named set, states in the verdict that account-wide enumeration was refused and that the table is the bound it checked against, and does not report the criterion as met on the wider reading. Closing the gap for real is an Owner-surface action — an account-wide listing from a surface that holds the credential — not something a run can reach. (Worked case: APP-1409's fifth criterion asked for the full in-scope repo list; QA verified all 16 named repos and could not enumerate the account, with nothing disclosing the gap to the reviewer — APP-1464.)

| Repo | Purpose |
| -- | -- |
| `assoc-one/claude-ops` | Skill, task, and routine artefacts (canon for the operating layer) |
| `assoc-one/assoc-one` | Association of One consultancy site |
| `assoc-one/aledpritchard-com` | Aled Pritchard personal/portfolio site |
| `assoc-one/meirionpritchard-com` | Meirion Pritchard portfolio |
| `assoc-one/agents-site` | The public os.Claude agents site — renders the fleet, skills, and canon from the published `claude-ops` mirror |
| `assoc-one/mbn-theme` | Made by — Neud Shopify storefront theme |
| `assoc-one/firmup` | A1 client engagement build (a1.firmup) |
| `assoc-one/gtd` | GTD automation (the `gtd.*` Apps projects — Capture, Configure, Build, Health, Home, Family, MBN, CareerOS) |
| `assoc-one/fitness` | Fitness app (React Native / Expo) |
| `assoc-one/careeros-web` | careerOS web product |
| `assoc-one/luna` | Luna MVP |
| `assoc-one/bot-trader` | Bot trader |
| `assoc-one/ds-poc` | Data science PoC |

## Branch naming

- **exec leg:** `claude/<ticket-id>` — e.g. `claude/app-144`. Always cut off fresh `origin/main`.
- **Cloud / web sessions with a designated branch.** A Claude Code on-the-web session is issued **one fixed designated branch per repo** (e.g. `claude/hopeful-cray-xoi698`) rather than a `claude/<ticket-id>` per ticket. In that case use the session's designated branch, and document the deviation from the `claude/<ticket-id>` convention in the PR body (per the repo's `CLAUDE.md`). The one-fixed-branch model is expected for cloud/web sessions specifically; a Cloud Routine (the delivery loop) still cuts `claude/<ticket-id>` per ticket. **Recreate after merge:** GitHub auto-deletes the branch on merge, so a subsequent ticket in the same repo and session must recreate the designated branch fresh off `origin/main` under the same name before working. (Worked case: A1-131, meirionpritchard-com session on `claude/hopeful-cray-xoi698` — APP-450.)

  - **After that auto-delete, `--force-with-lease` fails with `stale info` — prune first, then push plain.** Recreating the branch leaves the local remote-tracking ref (`origin/claude/<branch>`) pointing at the pre-merge commit while the remote branch no longer exists at all, and `--force-with-lease` compares against that stale belief rather than against the remote — so the push is rejected `! [rejected] ... (stale info)`, a **false negative about a missing ref**, not the concurrent-writer warning the lease form exists to give. The discriminator is the `git ls-remote origin <branch>` read this section already mandates below: where it returns a SHA the branch exists and the lease rule stands unchanged; where it returns nothing the branch is gone, there is nothing to overwrite and nothing to protect, so `git remote prune origin` to drop the stale tracking ref and then a **plain** `git push -u origin <branch>`. Do not reach for a bare `--force` here — the plain push is sufficient and correct. The remote-environment harness's branch-requirements text is the source of the trap: it says a force-with-lease push "is fine when the branch contains only already-merged history", which is true of the *history* and silent about the *missing ref*. Confirm `git ls-remote origin <branch>` against the repo before treating the ref as present; expected an empty result on a branch GitHub auto-deleted at merge. (Worked case: A1-540 on `assoc-one/meirionpritchard-com`, 2026-09-25, immediately after A1-534's PR merged on the same designated branch `claude/focused-meitner-g2zg3d` — the lease push rejected, `git ls-remote` confirming "couldn't find remote ref", then prune-and-plain-push succeeding with no force at all. APP-1770.)

  - **The sandbox cannot delete a remote branch, so a throwaway branch's cleanup is never the run's to finish.** `git push origin --delete <branch>` from the delivery sandbox fails with `fatal: the remote end hung up unexpectedly` — twice consecutively on a branch that ordinary pushes from the same sandbox had just written, so the egress path appears to refuse a **ref deletion** specifically rather than the push being broken. There is no MCP substitute: the GitHub toolset has `create_branch` and no delete. Consequences, in order of preference: **prefer not to create the branch** — where a workflow can be exercised by a label or a dispatch on a branch that already exists, do that instead of opening a throwaway PR; and **where a throwaway branch is unavoidable, name it on the ticket as residue for the Owner to remove in a batch**, rather than reporting the leg clean and leaving the branch to be found later. Merged PRs are not the gap — GitHub's *Automatically delete head branches* covers those, and is the behaviour the recreate-after-merge rule above is built on — the gap is exactly the **closed-unmerged** throwaway, which no repository setting covers. Unverified: whether the ref-deletion refusal is intended egress policy; whether the GitHub MCP genuinely has no delete-branch tool, since the MCP is not mounted on the refine surface and its toolset could not be enumerated; and whether *Automatically delete head branches* is enabled on any repo other than the one APP-450 observed it on. That flag covers those three premises only. The environment question rides on the Owner's standing sandbox-image action (APP-974, APP-935), not on a new ticket. (Worked case: A1-516's throwaway PR #180 on `assoc-one/meirionpritchard-com`, closed unmerged 2026-09-23 — `claude/a1-516-test` was left for the Owner to delete by hand. It recurs by construction: APP-1718's rollout proves the workflow per repo with a throwaway PR each time. APP-1724.)
  - **Collision — the designated branch already carries an open, unmerged PR for a different ticket.** The recreate-after-merge model assumes the prior ticket's PR has landed; it hasn't always. If a second ticket in the same repo and session comes up while the first ticket's PR on the designated branch is still open (e.g. Blocked pending a separate action, not yet merged), there is no branch to recreate — committing the second ticket's work there would land two unrelated tickets in one PR. In that case, cut a fresh `claude/<ticket-id>` branch off `origin/main` instead (the ordinary per-ticket convention), and document the deviation in the PR body alongside the reason (the designated branch's PR was still open). Return to the designated-branch model once that PR clears. (Worked case: APP-482, `claude-ops`, 2026-07-10 — APP-472's PR was Blocked and unmerged when APP-389 needed the same repo.)
- **The delivery loop's per-ticket branch supersedes the harness's generic branch instruction.** The remote-environment harness ships a generic "Git Development Branch Requirements" section naming one fixed designated branch per repo (e.g. `claude/amazing-pasteur-i7xnsr`) and saying never to push to a different branch without explicit permission. For any repo the delivery loop operates on, **`skill-build-ticket`'s `claude/<ticket-id>` per ticket governs** — it is the specific, in-domain instruction, and it is the only model that works for a loop carrying many tickets across many repos in one session, where each ticket needs its own PR. Follow the per-ticket branch, note the deviation in the PR body, and do not stop to ask. Stated here because the conflict is silent and otherwise depends on each run re-deciding to prefer the skill over the boilerplate. (Worked case: A1-209, `assoc-one/firmup`, 2026-07-14 — APP-522.)
- **Aled's branches:** `aled/<slug>` convention.
- Main branch is protected. Never force-push it.
- **Before pushing to `claude/<ticket-id>`, check the remote — the branch may already carry another run's work.** Read `git ls-remote origin claude/<ticket-id>` and look for an open PR on that head branch first. Where either exists with commits you did not write, never force-push over it: fetch it, read what it holds, and reconcile — build on it, or stop and name the conflict on the ticket. Any force-push to a branch another run or session may have written — every `claude/<ticket-id>` included, the post-rebase push among them — uses `--force-with-lease=claude/<ticket-id>:<sha>`, naming the remote SHA you last read, so a push that would discard a commit you have not seen fails instead of landing. A bare `--force` is for one case only: restoring a just-verified prior state you hold locally. **And before deriving a fix in a shared file, read who else is in it — the branch check above catches one run pushing over another, not two runs editing the same function on separate branches.** A ticket scoped and reviewed in isolation can be correct at every step and still need re-deriving, because the mechanism it patched was rewritten underneath it. So a build leg touching a file that carries a dense concentration of prior decisions reads two things before writing: the file's recent history on the authoritative remote tip, and the open PRs that change it. Where another open PR changes the same function, rebase and derive the fix against the shape that will exist at merge, and name the overlap on both tickets rather than leaving it for integration. The cost is one history read against a full round of re-verification. (Worked case: four tickets on `meirionpritchard-com` independently rewrote the mobile active-line mechanism in `WorkList.tsx` inside about 24 hours — two merged to `main` while two were still in flight on the old shape, and the in-flight one was rebased and re-derived only because its session happened to check `main`'s history first. Nothing surfaced the collision — `APP-1878`.) This binds interactive sessions as much as the loop: the delivery loop's run-level lock and concurrency guardrail are loop-only, and a session that checks Linear alone sees none of a concurrent run's GitHub state. (Worked case: an interactive session asked to write A1-448's file checked only Linear and force-pushed its build to `claude/a1-448` over another run's verified commit on draft PR #143; the commit was recovered from the local object database with `git show <sha>` and a second force-push, verified byte-for-byte — APP-1558.)

- **A plain fast-forward push onto a `claude/<ticket-id>` branch that already carries an open pull request is the same collision — needing no force does not discharge the check above.** The rule above is written around overwriting, so it reads as satisfied the moment a push is a clean fast-forward: nothing is lost, the lease would not have fired, and its own remedy — *build on it* — reads as licence to append. It is not. A commit for different work landing on a branch whose open pull request belongs to another ticket puts a change the Owner did not ask for in that session under that ticket's review, and a revert pushed after it leaves two unrelated commits in the pull request's history instead of removing the problem. The designated-branch *Collision* bullet above already rules this case correctly — cut a fresh branch rather than land two unrelated tickets in one pull request — and that answer is not special to the designated-branch model; it binds `claude/<ticket-id>` identically, and sitting only under the cloud/web bullet is why a per-ticket branch reads as uncovered. So the pre-push check reads the open pull request's **ticket**, not only its commits: where the PR belongs to a ticket that is not the one being worked, the push does not happen at all. Cut a fresh `claude/<ticket-id>` off `origin/main`; or, where the work has no ticket yet, take the ticketless branch form below rather than riding the open branch while the ticket is filed. That last case is the one that bites, because a ticket filed only afterwards never gave a second branch name to derive, which is exactly what makes the open branch look like the available surface. (Worked case: two sessions on `assoc-one/a1-advisory` both derived `claude/a1-871` from the same ticket id while pull request #39 was open; the second pushed an unrelated mobile-type change and then a revert of it a minute later, rejecting the first session's push twice as non-fast-forward, conflicting its rebase in `hero.css`, and cancelling and re-running CI on two intermediate heads — the second change's own ticket A1-872 being created only afterwards. Recovered by resetting to the remote and cherry-picking. The pull-request number, the branch, the commits, the CI re-runs and the conflict are **reported** from the filing note and were not re-observed here: `gh api repos/assoc-one/a1-advisory` returns 403 pending an `add_repo` grant on this surface and `git ls-remote` cannot read the repo at all. `APP-2839`.)

### Session instructions permit `--force-with-lease` where the auto-mode permission classifier denies it — name the disagreement and cut a fresh branch

**Where a session's own instructions permit a push that the auto-mode permission classifier denies, the disagreement is named in the run's report and the route taken is a fresh branch, never a retried force-push.** Restarting work on a `claude/` branch that has already been merged needs `--force-with-lease` by the rules above, and the auto-mode permission classifier refuses a force-push in any form — so the instruction layer and the permission layer disagree about one command, and neither layer says the other exists. A session that reads only its instructions stalls at the denial and spends the stall rediscovering a settled fact. Neither layer is wrong; they are scoped differently, and the fix is therefore a routing one and not an override. So name the disagreement explicitly — the instruction permits it, the classifier denies it, the denial stands — and take the route that needs no force at all: cut a fresh branch off `origin/main` under a new name and open the pull request from that, which is the same answer the prune-and-plain-push rule above gives for the deleted-ref case. Never substitute a bare `--force`, and never treat the denial as a prompt to escalate: in auto mode a permission denial is a stop. (Worked case: a restart on an already-merged `claude/` branch where the session instructions permitted `--force-with-lease` and the auto-mode classifier denied the same command, the run stalling until the fresh-branch route was taken. The instruction text, the denial and the stall are **reported** from the filing note and were not re-observed here, no session transcript or classifier decision being readable from the authoring surface. `APP-2823`.)

## PR conventions

- **Title:** `{TICKET-ID}: {short description}` — e.g. `APP-144: add content-engine skill`.
- **Body:** summary, acceptance criteria checklist (Pattern A), session link.
- PRs are opened by exec, never merged by exec — merge is Aled's via merge on the Relay signal.
- One PR per ticket. Never open a speculative PR.
- **Owner-ruled exception — several small changes to the same surface batch into one branch, one PR and one push.** Where several open tickets are each a small change to the **same surface** — a copy edit, a few lines, no behaviour — they are built on one branch, opened as one pull request and landed in one push, with every ticket named in the PR body and each of them closed on the merge. The reason is stated because a rule without it reads as laxity: one PR per ticket is a **review-isolation** rule, and a stream of one-line copy tweaks to one surface has no isolation to protect while each push bills a preview build. The prohibition above on a speculative PR is untouched by this and binds exactly as before. The exception does not reach a change that carries behaviour, a migration, or more than one surface: those take one PR each, whatever their size. (Owner-ruled in session 2026-11-12 on `APP-3084`: five consecutive one-line copy tickets on `assoc-one/aledpritchard-com` — `A1-989` through `A1-993` — each opened its own pull request, #94 through #98, most with a second push, and every push billed a Vercel preview build. Build CPU read 148 h at 72% of the cycle allowance against 117 h the prior period, +30%, and `aledpritchard-web` went 0 → 261 deployments since 2026-11-06 with 204 of those from feature branches. Those Vercel figures are **reported** — the CPU and allowance figures from a Vercel billing email, the deployment counts from the Vercel API as the filing leg read it — and were not re-observed here; the repo's share of the team total is **unverified** and no figure here apportions it. The platform-side half is **configuration and not canon** — an Ignored Build Step so a docs-only push does not build — and is the Owner's to set rather than authored on this page.)
- **A PR-create that fails with a 5xx is re-checked before it is retried.** The write may have landed, so call `list_pull_requests` filtered to the head branch first and retry only on an empty result — a blind retry is how the one-PR-per-ticket rule above gets tripped by a server fault rather than by the work. Transient 5xx on `create_pull_request` is observed and usually clears within a few attempts, so retrying is right; only the blind part is wrong. `gh` is not the fallback here, and its presence is not the test: the token can fail `gh auth status` while a repo-scoped REST read against an **attached** repo still returns data, so where `gh` is reached for at all it is reached for as `gh api repos/<owner>/<repo>/...`, never as `gh pr checks`, which goes through the refused GraphQL transport (*GitHub MCP tools*, measured on the Pulse cloud surface 2026-10-23). And dropping `draft: true` is never the remedy — drafts are supported on these repos, and opening a PR ready pre-empts QA's one signal. (Worked case: four consecutive 502/500 failures on `assoc-one/firmup-operator`, the fifth call succeeding with byte-identical arguments to the third, each retry preceded by a head-branch check returning empty — APP-1408.)

### A merge with open acceptance criteria is set Done by the Linear integration within seconds — re-read the state and revert it

**A merge of a pull request whose acceptance criteria are not all met is followed by a state re-read on the linked Linear ticket, and the integration's auto-transition to Done is reverted with the residue named on the ticket.** Linear's GitHub integration moves a linked ticket to Done within seconds of the merge, and it reads the merge alone: it has no view of the acceptance-criteria checklist in the PR body, so a partial-AC merge taken deliberately — landing what is ready and carrying the remainder — silently closes the ticket that holds the remainder. Nothing errors, nothing notifies, and no canon told the session to expect the transition or to undo it, so the loss surfaces later as a ticket nobody is working because the board says it is finished. So the merge is never the last write on a partial-AC ticket: re-read the ticket's state after merging, return it to the state the open criteria warrant, and name the residue in a comment — which criteria are unmet, and where they are carried — so the revert reads as a decision rather than as an unexplained board correction. Where the remainder belongs to a separate ticket, cite that ticket in the same comment. (Worked case: A1-844, merged with acceptance criteria still open and set Done by the integration within seconds, the transition neither anticipated by the session nor undone by it until it was noticed by hand. Every figure here — the transition, its timing and the ticket's open-criteria state at merge — is **reported** from the filing note and was not re-observed on the authoring surface, no repo, GitHub API response or integration log being readable from it. `APP-2828`.)

## GitHub MCP tools

MCP tool schemas are not auto-loaded. Run `ToolSearch` with `select:mcp__github__<tool-name>` before the first call to any GitHub MCP tool. Key tools: `mcp__github__create_pull_request`, `mcp__github__list_pull_requests`, `mcp__github__push_files`, `mcp__github__get_file_contents`, `mcp__github__add_issue_comment`, `mcp__github__merge_pull_request`.

**In the delivery sandbox the GitHub MCP tools are the only working route, and `gh` is never assumed — its presence varies by surface, and a `GITHUB_TOKEN` that is *set* is not a `GITHUB_TOKEN` that *works*.** Three states have been measured, and canon names all three rather than picking one, because a leg reading only one of them draws the opposite conclusion about whether a CI watch is possible: **(a) `gh` absent** — `gh: command not found`, on the delivery-loop sandbox 2026-08-15 and 2026-08-16 (APP-935, APP-974) and again on the refine surface 2026-09-23; **(b) `gh` installed but its token a placeholder**, so `gh auth status` reports it invalid and the documented watch patterns return nothing useful, with GraphQL refused outright and some REST paths proxy-rewritten (APP-935, APP-1353, APP-1461, APP-1482 — see *Reading CI / PR state in autonomous runs*); **(c) `GITHUB_TOKEN` set to a literal placeholder** — measured as the string `proxy-injected` on the refine surface, 2026-09-23 — the APP-1032 false-positive shape: set, non-empty, and useless. So **"is `gh` installed?" and "is `GITHUB_TOKEN` set?" are both the wrong test.** **The capability test is one repo-scoped REST read that returns data, and `gh auth status` is not it.** Measured first-hand on the Pulse cloud surface on 2026-10-23, by three independent readings: `gh auth status` reports *"The token in GH_TOKEN is invalid"* while `gh api user` returns **HTTP 200** as `assoc-one` (id 206522078). **REST authenticates, and the tool's own self-report says it does not** — the direction that costs, because it reads as a closed route while the route is open. So the test is **one repo-scoped REST read against an attached repo that comes back with data** — `gh api repos/<owner>/<repo>/commits/<sha>/check-runs` returning a non-empty array, or one `mcp__github__*` read returning the expected object. `gh auth status` is a statement about the token the client holds, not about what the surface can reach, so it is never the probe and its failure is never the conclusion. **`gh pr checks` is disqualified as a probe whatever it returns**, because it goes through GraphQL, which is refused outright from Claude Code sessions with a 403 naming REST as the route — its failure is a transport fact and carries no information about the credential at all. **And repo attachment is a third axis beside the binary and the credential.** On the same surface and in the same minute as the 200 above, `gh api repos/assoc-one/meirionpritchard-com/pulls/107` returned **403** — *"GitHub access to this repository is not enabled for this session. Use add_repo to request access"* — and `gh api user/repos` returned 403 naming sessions as bound to their configured repositories. A 403 naming `add_repo` is **not an auth failure and is never read as one**: the credential is working, the repo is unattached, and the remedy is `add_repo` rather than a different token. So state (b) is narrower than it reads — a token that fails `gh auth status` can still carry repo-scoped REST — and the three states above are crossed by a fourth question no credential test can answer, *is this repo attached?* The MCP stays the route to prefer where it is mounted; where it is not, a repo-scoped REST read against an attached repo is a working route rather than an absent one. What does not work here is GraphQL, an unattached repo, and `git ls-remote`, which still fails for want of a usable git credential. **Every figure in this paragraph is observed on the Pulse cloud surface on 2026-10-23 and nowhere else.** The delivery sandbox is a different image and is not readable from here, so none of it is asserted of that surface — the probe is the same there and is run there rather than inherited from this paragraph. State (c)'s placeholder shape held on this surface: `GITHUB_TOKEN` and `GH_TOKEN` both read 14 characters with the prefix `proxy-`, which is consistent with the 2026-09-23 `proxy-injected` reading rather than contradicting it, and is carried as a shape and never as a value — **observed once in origin**, on one surface, and re-measured the same day. The MCP cannot be driven from `Monitor` or a background bash loop, so **CI watching is hand-polled by design** — poll the MCP between time-based `sleep`s (the bounded-wait pattern in *Reading CI / PR state in autonomous runs*), never delegate the watch to a background process. The environment fix — install `gh` **and** expose a *valid* `GITHUB_TOKEN` in the sandbox image, since state (c) shows either one alone is not enough — is an Owner image/environment action, the same family as the Sanity egress allowlist gap (APP-712); a run cannot fix it for itself, only work through the MCP. **APP-974 and APP-935 remain open (Blocked) on that Owner action**: this entry removes the contradiction they sat behind, it does not close them. (APP-974, APP-935, APP-1032; reconciled on the refine surface 2026-09-23.)

## Writing files in autonomous / cloud runs

When an unattended run needs to write files to a repo — a publish commit (ops-sync), or any commit the exec or merge leg makes — commit them through the GitHub MCP (`mcp__github__push_files`), **not** local `Write` + `git commit`. A local write to a sensitive path (a `SKILL.md`, for instance) trips Claude Code's interactive permission gate; with no one present to approve, the prompt times out ("Stream closed") and the run stalls — one overnight run hung 11 hours this way (APP-318, 2026-06-26). `push_files` commits via the API and never raises that gate. Parallel local writes make it worse — every file prompts at once — but the root cause is the interactive gate, not the parallelism, so routing the writes through the MCP resolves it regardless of count.

This is the file-write rule for unattended runs only. An interactive local session, where the operator is present to approve prompts, is unaffected and may use either path.

### The default is for new files and whole-file replacements — an edit to a large existing file takes the local path

`push_files` takes each file's full content inline, so following the default on an *edit* means re-emitting every unchanged line of the existing file by hand through a tool call. That collides with *The digest block in the PR body is generated output, never retyped* below: re-emitting two hundred lines is the same hazard as retyping a digest, at larger scale and with the worse failure mode — a transcription slip in the *unchanged* part of a file lands in the commit looking like intentional work, and nothing downstream recomputes it. The two rules are both right, so the boundary is written down rather than re-derived per run.

- **A new file, or a whole-file replacement the run is authoring anyway** — `push_files`. Nothing is being reproduced, so there is no retype hazard and the APP-318 gate rationale applies undiluted.
- **An edit to an existing file whose unchanged portion would otherwise be re-emitted** — local `Edit` + `git commit` + `git push`, under the author rule in *Local git operations*, **and only where a local write has already landed in this session without raising the approval gate**. That condition is evidence, not prediction: APP-318 cost eleven hours to a prompt nobody could clear, so a run that has not yet demonstrated the gate is quiet must not discover it on a write it cannot abandon.
- **Where the gate has not been demonstrated quiet**, `push_files` stands, and the content handed to it is read back from the file on disk (or `get_file_contents`) immediately before the call rather than reconstructed — read, send, diff the two, which is the same generate-and-verify shape the digest rule uses.

**Name the path taken in the PR body, one line, with the reason.** The collision is silent, each run meets it fresh, and an unrecorded deviation leaves the next run re-deriving the answer — the recurrence shape branch naming already carries (APP-695). (Worked case: APP-1228 / `claude-ops` PR #195, 2026-09-10 — one section appended to a ~200-line `CLAUDE.md`; the leg took the local path on the grounds that its earlier local write had landed ungated and the retype hazard was the larger of the two risks, and did not record the deviation in the PR body — APP-1287.)

## Publish tickets targeting claude-ops — the manifest mirror

A publish ticket (ops-sync raising Claude-ahead-of-repo canon to `claude-ops`) commits a `canon/skills/<name>/SKILL.md` — or `canon/tasks/<name>/SKILL.md` for a `task-*` — but that alone is not enough: the repo's CI runs a "Build manifest" gate that checks committed `public/` files match what `build-manifest.ts` generates, and a commit that touches only the `SKILL.md` fails it with "Committed manifests are stale — run `npm run build:manifest` locally and commit the result."

**Prefer running the script — it is the safer path and it does run here.** In the Cloud Routine environment, `npm install && npm run build:manifest` runs cleanly in the `claude-ops` clone and regenerates every `public/` record and download, after which the staleness gate passes (worked case: APP-690 / APP-691 publish tickets, both green on the gate after running it, with QA independently confirming a zero diff — APP-697). This supersedes the earlier "a cloud/unattended run cannot invoke that script locally" wording, which was demonstrably wrong and steered runs toward hand-construction, the riskier path. The *Fresh clones* rule already assumes the script runs (it "errors clearly, because it needs `tsx`"); `npm install` supplies `tsx`, so run the install first (see *Fresh clones*), then the script.

- **Before touching any canon file, run `npm run build:manifest` on the untouched tree and confirm a zero diff.** That establishes the committed mirrors were already in sync, so the regeneration afterwards is attributable to your change alone rather than to accumulated drift.
- Make the `SKILL.md` change, then run `npm install && npm run build:manifest` and commit the `SKILL.md` together with everything the script regenerated under `public/`.

**Hand-construct the mirror only as a genuine fallback** where the script cannot run on the surface — and if you do, two traps make it error-prone, which is the reason to prefer the script:

- **The prefix trap — the prefix is conditional, not unconditional.** The disambiguating `task-` prefix is applied **only where the name does not already start with** `task-`. Under the current `<type>-<name>` convention every task name already carries it, so a `task-*` artefact is mirrored at exactly `public/downloads/<name>.md` — `task-content-drain` at `public/downloads/task-content-drain.md`, with no `task-task-` basename anywhere. **The download-path rule lives in `skill-ops-sync`** (*Read the download path from the manifest, never construct it*) and is not restated here: read it there for the read-side rule, for the APP-728 / APP-802 fix it came from, and for why a hand-built path shipped the APP-802 / APP-1190 404s. **This bullet asserted the doubled prefix as present fact, and was wrong — wrong since APP-802 landed.** Two live canon artefacts contradicted each other using the same artefact-name family as the example, and `skill-ops-sync` is the one that was right. A leg reasoning from the old wording looks for `task-task-<name>.md`, does not find it, and reports a missing download and a failed render on a sound publish — confidently, by following canon. So what makes hand-construction error-prone here is the **conditionality** rather than the prefix: the naive rule and the real one agree on today's data and will diverge the moment a name arrives without the prefix, which is the one case nobody is watching for. Apply the condition rather than the shape, and cross-check the result against the existing `public/downloads/` listing before committing — a `task-task-` basename in that listing is the signature of the old rule, not of the current one. **The mechanism is a repo fact and is unverified from the drain surface:** no repo is readable here, so canon states the rule as canon holds it and asserts nothing about `build-manifest.ts`'s branching in either direction. The probe that settles it is to read `scripts/build-manifest.ts` on `origin/main`, which APP-2395 already carries and which still gates APP-1850. That premise covers the script's prefixing logic alone and implies nothing about any other repo-side premise on this page.
- **The manifest–summary coupling.** The manifest entry's summary derives from the frontmatter `description`, so an artefact whose *description* changed also changes `manifest.json` — even when no `type:` field moved. Leaving the manifest untouched on a description-only change (as the older rule implied) misses this and fails the gate.

Missing the mirror entirely costs a second commit and a stale QA verdict once the SHA changes after review has already posted (worked case: APP-339, 2026-06-27, APP-346).

### The digest block in the PR body is generated output, never retyped

Parity on a byte-exact publish is asserted from the digest and never from the diff's shape (`skill-ops-sync`), and `skill-build-ticket` already forbids hand-transcribing an *expected* digest read from a ticket. The gap is the other direction: the digest block the run writes into the PR body, which is the artefact Prism reviews parity from and the operator gates on. **Generate that block from `sha256sum` output and paste it verbatim; never retype a digest.** Where a run has already written one by hand, repair it by writing the PR body's block to a file and `diff`ing it against live `sha256sum` output — not by re-reading it, which is the check that fails. (Worked case: APP-1153, `claude-ops` PR #185, 2026-09-07 — five canon artefacts committed byte-for-byte, all five verified against their digests before commit, and one of the five mistyped in the PR body, `…faf6a8c…` for `…fd3f5a8c…` on `task-goal-review`. The repo was never wrong; only the attestation was. The error sat mid-string in a 64-character hex digest whose first and last eight characters were correct, which is the shape human and model proofreading both skip — APP-1159.)

Both failure modes cost, and the quieter one costs more: a wrong digest against a file that is in fact correct stalls review on a defect that does not exist, and a wrong digest that happens to match the wrong file attests to a parity that does not hold, with nothing downstream recomputing it. The surface is large — around thirteen batches of publish tickets, each carrying a five-to-ten row digest table, all currently transcribed by hand — and the check costs one command.

**The rule generalises past digests: any machine-checkable value a run copies into a review-facing surface is generated and pasted, never retyped, and is verified by diffing against live output rather than by re-reading it.** Byte counts, commit SHAs and run IDs have the same shape — a value the run already established mechanically, then re-entered by hand into the body a reviewer trusts. Re-reading cannot catch a mid-string transcription error, because it compares the value against a memory of itself; diffing compares it against the source. Stated in the general form so it does not need re-authoring per value type, with the digest block as its most-used instance (APP-1159). **And the verification is scoped to the whole body, not to the block.** The repair above writes the PR body's digest *block* to a file and diffs that block, which is the right check on the wrong extent: a restated digest, file count or path list in the prose around it is outside the diff, so a slip there survives a repair that reports clean, and it survives with the block's own verification standing behind it in the reviewer's eye. So extract from the body **as written** every run of 40 or more hex characters and every restated file list, and check each one's **length and value** against the generating output rather than against the eye — length first, because a dropped or doubled character is the cheapest slip to make and the one a value-only comparison of two near-identical strings is least likely to surface. A hex run shorter than its type allows is wrong whatever it matches. (Worked case: a 63-character base digest, mistyped in a pull request's prose on the second slip of the same pull request, caught by exactly this control — the length check on an extracted hex run, where the block-scoped diff had passed. The figures and the pull request are the filing leg's report and are unverified here; no repo is readable from this surface. APP-2384.)

## Attribution bytes at the end of an agent-authored body are rewritten in transit — read back and repair

A write path between the agent and GitHub **silently rewrites the trailing attribution bytes of a body it carries**, and it does so in all three directions: it **adds** a footer that was not sent, **appends** one below the bytes that were sent, and **replaces** the footer that was sent with a different one. Sixteen instances across six distinct write paths, which is why this is a class and not a quirk of one tool — the path count is read off the list below and the instance count is **reported** from the filing notes:

- A REST **PATCH** of a pull-request body mutates in **either** direction, so the route is characterised by what the read-back shows, never by the direction last recorded. It **added** a second "Generated by Claude Code" footer below the one already there (APP-2378, the predecessor of this class). On a later run through the same route it **replaced** the mandated footer instead: a body fetched byte-exact, edited by one checkbox line and sent back with `gh api -X PATCH repos/{owner}/{repo}/pulls/{n} -F body=@file` came back with the session-mandated "🤖 Generated with [Claude Code]" line removed and a horizontal rule plus an italic "Generated by Claude Code" link appended after the session link — the `create_pull_request` shape of this class on the one route previously recorded as doubling only. The detector and the repair below are what held: the read-back diff found it, and `mcp__github__update_pull_request` with the body inline stored what was sent. The practical consequence sits in `skill-review-pr`'s *Tick the PR body's copy*, whose strip-the-footer-first step answers the appending direction and makes the replacing one worse. (The A1-728 QA leg, `assoc-one/meirionpritchard-com` PR #257, head `775db5b`, 2026-10-21, repaired with the 13,988-byte body inline — APP-2581. The pull request number, the head SHA, the byte count and the read-back bytes are the filing leg's report and are **unverified** here, no repo, pull request or GitHub API response being readable from the authoring surface, and a flag on one implies nothing about the others.)
- `mcp__github__create_pull_request` **replaced** the mandated footer. The body was sent with the session-mandated "🤖 Generated with [Claude Code]" line plus the session link; read back with `pull_request_read get`, it ended instead with a horizontal rule and an italic "Generated by Claude Code" link, and both mandated lines were gone. Nothing errored. A later `update_pull_request` carrying the same footer stored it intact, so on this evidence the rewrite is specific to the **create** call rather than to the body (APP-2471).
- `gh api …/comments -F body=@file` **appended** a footer below the intended bytes on a comment POST (APP-2474, the secondary observation).
- `mcp__github__add_issue_comment` **added** a footer below the bytes that were sent, on a comment **create**. The carrier was a QA verdict comment, so the appended line sits directly under the verdict's own last line and reads as part of it (comment 6306287812 on `assoc-one/claude-ops` PR #501, head `8205db6`, the APP-2493 QA leg, 2026-10-21 — APP-2507).
- `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<id> -F body=@file` **appended** the same footer a second time, two blank lines down, when it was taken as the *repair* for the bullet above. A comment PATCH is a distinct path from the pull-request-body PATCH that opens this list, and it is the one path observed leaving the body worse the more it is used (APP-2507).
- The comment **POST** of the bullet above recurred the same day on a second verdict comment: `gh api repos/assoc-one/claude-ops/issues/503/comments -F body=@verdict.md` appended a horizontal rule and an italic "Generated by Claude Code" link below the sent bytes (comment 6306723393, PR #503, head `735e74c`, the APP-2491 QA leg — APP-2507's thread). The `[qa] HEAD:` first line and the verdict body were intact; only the trailing bytes moved, which is the shape of every instance in this class.

**With these two, the section names six rewriting paths and one that held, so the route is not the control.** Rewriting: a REST pull-request-body PATCH, `mcp__github__create_pull_request`, a REST comment POST, `mcp__github__add_issue_comment`, and a REST comment PATCH — both verbs, both clients, and both body kinds. Holding: `mcp__github__update_pull_request` for a pull-request body — and on the comment side, nothing: **the comment-side entry in this tally is retracted below**, which withdraws `mcp__github__update_issue_comment` with the body inline as a holding route rather than narrowing it, so this tally names a pull-request-body route only (`APP-2948`). On the comment side specifically, all four of the comment-side routes taken in anger have rewritten the trailing bytes and none has held, and the single route that still holds is an MCP edit call on the pull-request side — which is why read-back here is unconditional rather than path-selective: picking a route is a guess about a mechanism nobody has identified, and reading back is a measurement.

**The verdict comment is the named carrier of this class.** A QA verdict is written as a comment to both the Linear ticket and the GitHub PR, it is the merge gate's own evidence (`skill-merge-pr`'s `[qa] HEAD: <sha>` record), and its last line is exactly the region a reviewer's eye skips — so an appended footer lands under a verdict body that is otherwise intact and reads as part of the verdict. That makes the comment read-back a **diff of the trailing bytes against the file that was sent**, never a presence check: the comment is present, correct and complete in the failing case. `skill-review-pr` carries that obligation on the comment at its *Read-backs* section, pointing here for the path list rather than restating it.

**So read back and repair after any agent-authored pull-request body or comment body write.** Fetch the stored body, compare its trailing bytes against what was sent, and re-write through a route observed to store what was sent — `mcp__github__update_pull_request` for a pull-request body, which still holds and is unchanged by this entry. **On the comment side there is no such route: no comment route on this surface stores byte-exact.** This retracts this section's own earlier claim that `mcp__github__update_issue_comment` with the body inline was a comment route whose read-back held byte-identical to the file that was sent — that route has now itself appended the generated-by footer to a QA verdict, so the claim is **withdrawn, not narrowed**, and both the *Holding* tally above and the inline-`mcp__github__update_issue_comment` repair clause below are superseded on the comment side by this paragraph (`APP-2888`, **reported**; sixth-and-later recurrence of one root — `APP-2507` → `APP-2644` → `APP-2749` → `APP-2784` → `APP-2836`, all closed — with five further same-day instances reported on its own thread). The detection half of this section took hold; the named repair route did not, which is what retires it rather than re-trying it. **So a comment body is written once with the footer already stripped, and the removal is disclosed on the ticket.** Strip any existing generated-by footer from the body file before the write — this section's own strip-then-write instrument, now the comment path rather than the fallback — write once, read back and diff by the parsed JSON `body` instrument below rather than by `gh api … --jq .body`, and never take a second write as the repair, which is the one move measured here as leaving the body worse. Then say on the ticket that the footer was stripped before the write and that no comment route is byte-exact, so the comment's trailing bytes are evidence of neither the sender's bytes nor a clean carrier. **The upstream half is not canon's to fix and is not filed:** whatever proxy or GitHub-app layer injects the footer below every route is an Owner control-plane lever — the GitHub-app / proxy footer-injection setting on the Owner's surface — carried as a **config action**, named and never filed, because no run can reach it and no canon change substitutes for it. Falsifiable: where that config action lands and a comment write then reads back byte-identical on two consecutive verdicts by **2026-12-15**, this retraction is wrong and the repair route returns. **Every repo-side figure below is the filing leg's report and unverified here:** confirm `assoc-one/a1-advisory` against the repo before writing it; expected pull requests `#613`–`#618` with the `A1-900` / `a1-advisory` `#55` particulars, and confirm each comment ID and head SHA against the repo before writing it; expected the IDs and SHAs the filing note reports. The probe is the one this page already names: `gh api user` returns 200 as `assoc-one` on this surface while unattached repos, public ones included, return 403, so no repo is readable from here and that premise stays **unverified** in every output this row carries. **And the instrument for that diff is the parsed JSON `body`, never the raw output of `gh api … --jq .body`.** The rule above fixes what to compare and names no tool, and the obvious tool manufactures a false red: jq terminates its output with a newline, so a body stored byte-identical to the file that was sent comes back one byte longer and diffs as one extra trailing blank line — in exactly the trailing region this check exists to inspect, and indistinguishable at a glance from the appended-footer failure it is hunting. Observed on the authoring surface: a 17-byte body sent and 18 bytes read back through `jq -r .body`, with `diff` reporting *"No newline at end of file"* against the sent file, while `json.load(raw)['body'] == open(sent).read()` returned `True` on the same pair (`/usr/bin/jq` 1.7; `gh` 2.89.0 at `/usr/local/bin/gh`). So spill the API result to a file and lift the field — `python3 -c 'import json,sys; d=json.load(open(path)); …'`, the same idiom the spill-and-slice rule below prescribes for recovering a field out of a result — then compare that string against the bytes that were sent. `gh api … --jq .body | head -c -1` is a shell **fallback** only, observed returning the same 17 bytes identical to the sent file, and it carries a caveat the parsed compare does not: it strips one trailing newline unconditionally, including a newline the stored body may genuinely end in, so it can mask a real trailing difference where the parsed compare cannot. **Whether gh's own embedded `--jq` behaves identically to `/usr/bin/jq` is unverified, and that is the premise** — no GitHub API response is reachable from this surface, so the one-byte read-back observed on the filing leg's own pull request is its **report** and was not re-derived here. The remedy rests on it in neither direction: the parsed compare never invokes jq at all. (Worked case: the `APP-2744` QA leg, `assoc-one/claude-ops` PR #570, head `03618f9`, 2026-10-29 — a REST comment POST appended the generated-by footer, the inline `mcp__github__update_issue_comment` repair stored what was sent, and the `--jq .body` re-read then showed a one-byte difference that a parsed compare of the same pair declared identical; **reported**, per the flag above. `APP-2748`.) **A REST comment PATCH is not a repair route**: taken as the repair for an appended footer it appended the footer a second time, so the body came back carrying two footers instead of one and the repair cost more than the defect. Where the clean route is out of reach on the surface in hand — the Claude Code auto-mode classifier denies some REST writes outright, or the GitHub MCP exposed to the session carries `add_issue_comment` with no comment-update tool at all — strip any existing generated-by footer from the body file before the write, then diff, rather than treating the second write as a fix. **An absent repair route is not a reason to stop at one PATCH and disclose the footer**: the surfaces differ run to run on this exact tool, so the route is established by reading the session's own roster rather than from canon or from a previous run's success, and the strip-then-write path is the fallback wherever the read comes back without it. **Read-back is the only detector**: the call does not error, no status signals the substitution, and the rendered result looks ordinary — an attribution footer is exactly the region a reviewer's eye skips, so a wrong one reads as the right one and a doubled one reads as the page. This is the same generate-and-verify shape the digest rule above uses, pointed at the end of the body rather than at a value inside it: compare against the source, never against a memory of what was sent. Where the write path is a `create` call, read back immediately rather than at hand-off, because an intervening write of any kind makes the substitution unattributable. Canon carries no other PR-body-footer rule, so this is a new rule rather than a correction, and the exact footer text a session mandates is set by that session and is not canon's to fix — the rule is that what was sent is what is stored, whatever was sent.

**Every instance detail above is a reported premise from the filing legs and is unverified here** — no repo, pull request or GitHub API response is reachable from this surface. The flag covers, each clause covering itself alone: that the PATCH added a second footer; that the `create_pull_request` body was sent with the mandated lines and read back with them replaced; that a later `update_pull_request` with the same footer stored it intact; and that the `gh api` comment POST appended. A flag on one implies nothing about the others, and the rule depends on none of them individually — sixteen independent reports of trailing attribution bytes differing from what was sent make read-back cheap insurance whatever the mechanism turns out to be. (APP-2471, with APP-2474 as evidence.)

**A comment whose body must be byte-exact is read back after it is posted, and a marker asserted without that read-back is unverified.** **And this paragraph's repair clause is superseded: the route is strip-then-write-once, not a second write.** Where the read-back diff shows the stored body differs from what was sent, strip the generated-by footer from the body file and **write once**, then read the stored body back and diff it by the parsed-JSON instrument this section prescribes; the repair write through `mcp__github__update_issue_comment` **carrying the body inline** is **retired**, that route having itself appended the footer. Measured across **sixteen** instances, every one a comment write that came back longer than the bytes sent, while `mcp__github__update_pull_request` read back **byte-identical at 4,130 / 4,339 / 4,459 / 6,133 B** and Linear's `save_comment` stored clean on the same runs. That contrast **localises the injection to GitHub's comment carrier**, not to the agent and not to the client: the same body, the same session and the same strip step pass through two other carriers unchanged. (All sixteen instances, their byte counts and their pull-request numbers are the filing legs' **reports** — the tally rising from nine by the tenth instance asserted on `APP-3061`, whose closure *assessed, not warranted* withdrew the canon change and not the instance, and by `APP-3082` together with five further occurrences on its own thread; no repo and no GitHub API response is readable from the refine surface, and that is the premise. `APP-2948`.) The repair rule above binds any agent-authored body; this names the carrier class that cannot absorb a single appended byte and makes the read-back a precondition of asserting anything at all about the comment. `mcp__github__add_issue_comment` appends a "Generated by Claude Code" attribution footer to bodies the agent sent clean, and the bodies that cannot survive it are the ones read downstream as bytes rather than as prose — a QA verdict, whose appended line lands under an otherwise intact verdict, and a `REVIEWING` marker, whose whole function is to be matched exactly. Nothing errors in either case. So any comment whose body is load-bearing at the byte level is read back immediately after posting, diffed against the bytes that were sent by the parsed-JSON instrument the rule above prescribes, and repaired with `mcp__github__update_issue_comment` **carrying the body inline** wherever the stored body differs from what was sent; and a pass that asserts a verdict or a marker landed without having run that diff has made an **unverified** claim and reports it as one rather than as a verdict. Recurrence well past a tenth instance on this one route is what makes the read-back a step here rather than a caution. (Worked case: the `APP-2818` QA leg, where the read-back diff caught the appended footer and `mcp__github__update_issue_comment` with an inline body restored the comment byte-identical — 5355 bytes sent against 5413 read back on PR #597, and the same recipe exercised on PR #602 at head `c6aa615`. The recipe was **observed** by the leg that ran it; every byte count, pull-request number and SHA is that leg's **report** here and was not re-derived, no repo or GitHub API response being readable from the authoring surface, and the recurrence count is likewise reported. `APP-2836`.)

## Fresh clones — `npm install` before the *first* npm script of any kind

An unattended run works from a fresh clone with `node_modules` absent. Run `npm install` before the **first npm script of any kind** — format, lint, format-check, type-check, build, test — not only before the scripts that hard-fail without dependencies.

The reason is that a pre-install script does not reliably fail. `npm run build:manifest` errors clearly, because it needs `tsx`, and a clear error is easy to catch and correct. But `npm run format` and `npm run lint` can **silently succeed** against whatever Prettier or ESLint the environment happens to expose, applying a different version's rules than the repo's pinned toolchain: files are rewritten, `git status` shows them modified, and the diff looks legitimate while being pure noise. Running `npm install` and the same script again reverts it. A script that succeeds against the wrong toolchain is a worse trap than one that errors, because nothing signals the mistake and the noise commits cleanly alongside real work.

So this is an ordering rule, not a judgement call: install first, then run anything. (Worked case: A1-211, `assoc-one/firmup`, 2026-07-15 — a pre-install `npm run format` rewrote `src/lib/types.ts` union-type wrapping and cost a revert-and-recheck cycle; caught before commit — APP-529.)

**Install is not the last precondition — build any generated input the repo names before the first type-check or test.** Some repos gitignore files that a type-check or a test imports and write them from a content or codegen step. On `agents-site`, `content/` is produced by `npm run build:content`, which runs as the first step of `dev` and `build` but not of `tsc` or `test` — so those are the two commands that do not get it for free. In a fresh clone, after `npm install` and before the first type-check or test, run every generation step the repo's `CLAUDE.md` or `package.json` names, with whatever it needs set explicitly (on `agents-site`, `CANON_DIR`). A failure that traces to a missing generated input — `Cannot find module` on a gitignored path, a test red against an absent file — is environmental, not a defect in the PR under review: satisfy the precondition and re-run before reporting, and never bounce a PR, or read the exec leg's figures as an overclaim, on that result. A base-versus-head gate comparison runs the generation step on both sides. Where a repo leaves the step out of its type-check and test scripts, chaining it in is the structural fix, and it is repo-lane. (Worked case: A1-451 QA leg, `assoc-one/agents-site` PR #15, 2026-09-21 — a fresh clone after `npm install` gave three TS2307 errors on `content/*.json` and 37 pass / 2 fail; after `build:content`, `tsc` was clean and 68/68 passed, matching the PR's own claim — APP-1598.)

### A worktree needs its own `node_modules` — hard-link it, never symlink it

A git worktree does not share `node_modules` with the checkout it was cut from, and a leg now works in its own worktree as a matter of course, so every leg meets this. Do not symlink the sibling's directory: Turbopack rejects a `node_modules` symlink that points outside the project root — `Symlink [project]/node_modules is invalid, it points out of the filesystem root` — and the message names neither the symlink nor the remedy, so a build failing seconds after checkout reads as a bad head or a broken checkout rather than as a setup shortcut, and a leg that has just wiped its build output for a measured build is primed to blame its own hygiene. Hard-link it instead: `cp -al ../<sibling-checkout>/node_modules ./node_modules`. It is safe because both trees are pinned by the same commit's lockfile and hard links share inodes rather than mutating them, and it costs about a second against the minutes a cold install costs. Fall back to `npm install` where the lockfiles genuinely differ, where the sibling sits on a different filesystem, or where the repo's dependencies carry post-install native builds or a patched package. The ordering rule above is unchanged — it governs *when* a script may run, this governs *how the directory gets there*. (Worked case: A1-386 round-2 QA, `assoc-one/firmup-operator`, 2026-09-08 — a symlinked `node_modules` in a fresh worktree cost a failed build cycle and its diagnosis; the hard-link copy fixed it in one command. APP-1199.)

## Local git operations — clone-and-commit runs (rebases)

`push_files` is the default for unattended writes (above), but it cannot rebase — so an exec or merge leg that has to rebase a PR branch onto an advanced `main` clones the repo and commits with local `git` instead. Three things bite that path, each of which cost real recovery on a live run (worked case: A1-130, `assoc-one/meirionpritchard-com` PR #46, 2026-07-07). Follow all three whenever a run commits from a local clone rather than `push_files`.

- **Set the commit author to `Claude <noreply@anthropic.com>` before committing — not an arbitrary placeholder.** Vercel's GitHub integration requires the commit author's email to match a linked GitHub account; an unrecognised address (a placeholder such as `forge@assoc-one.dev`) fails Vercel's status check with "No GitHub account was found matching the commit author email address", so `mergeable_state` sits at `unstable` even when CI (Playwright) is green. `Claude <noreply@anthropic.com>` is the identity the repos' history already uses and the one Vercel accepts. Set it first — `git config user.name "Claude" && git config user.email "noreply@anthropic.com"` — rather than rewriting a bad commit's author after the fact (`git filter-branch` / interactive rebase) to clear the check.
- **`git fetch --unshallow` before rebasing — never rebase a `--depth 1` clone onto a shallow slice of the target.** A shallow branch shares no merge-base with a shallow-fetched slice of `main`, so `git rebase` finds no common ancestor and treats *every* file as an `add/add` conflict — a wall of conflicts across unrelated files. Un-shallow first (`git fetch --unshallow origin`, or clone without `--depth`), and confirm `git merge-base HEAD origin/main` succeeds before rebasing. A shallow rebase that auto-resolves can silently produce a bad merge in the wrong direction, so do this even when the rebase does not fail outright.
- **Re-read the authoritative remote tip immediately before the final push.** `main` can advance several times within a single ticket's exec cycle when other runs land merges on the same repo concurrently (A1-130 needed three rebases across roughly 10 minutes). Check the real remote tip with `git ls-remote origin main` — not a possibly-stale local tracking ref — just before hand-off, and rebase again if it has moved. **This binds a run that has not rebased at all.** The section's framing assumes a leg already rebasing, and the word "again" reads a session that cut once and never took base back out of the rule — which is the run with the longest window for `main` to move. So **any** run that pushes to open or update a pull request re-reads the remote tip first and merges or rebases its base in where it has moved, whether or not it has rebased before and whether or not anything conflicts: a clean merge base is not a current one, and the pull request's own base being current says nothing about the branch's. **And the ref is the branch's own base, not the literal `origin/main`.** On a stacked pull request, or one opened against an integration branch, the base is some other ref, so the rule is read from the pull request itself: read its **`base.ref`**, re-read **that** ref's tip, and merge it in where it has moved — **before the final push, and again before a preview is handed over for review**, which is the second moment the branch can go stale without anything erroring. A run that re-reads `origin/main` on a pull request based elsewhere has run the check against the wrong ref and will report it as passed (`APP-2918`). `skill-build-ticket` step 5 is this obligation inside the delivery loop and discharges it there; an interactive or designated-branch session loads no `skill-build-ticket`, and `skill-merge-pr`'s base-moved check catches it a lane later and only where that leg holds a checkout — which is the surface this leaves uncovered. The failure is silent by construction: no conflict, no textual marker, green CI, and a preview that renders perfectly without the commits it is missing, so nothing short of this read surfaces it before the Owner does. (Worked case: 2026-10-06 — a session branch cut off `main` at session start was pushed and put up as a pull request while `main` had moved two commits ahead; the pull request's base was current and the branch's merge base was not, the preview built without the latest `main`, and it was caught the next morning by the Owner asking why the build was not built off the latest `main`. The commits did not overlap the change and merging `main` in was clean, so the cost was one Owner question and one merge commit; on a change touching the same files it is a conflict found late. Every repo, branch, pull-request and commit fact here is **reported** from that session and not observed — no repo is readable from the refine surface — APP-2182.)

### Building a fixture repo for a script that fetches from `origin` — two sandbox facts, one of them cosmetic

A script under test that runs `git fetch origin main` needs a fixture origin, and the obvious recipe — `git init --bare` plus a seed repo that pushes into it — appears to fail in the sandbox. Only half of what it prints is real, and it is not the alarming half.

- **`fatal: expected 'acknowledgments', received 'packfile'` is cosmetic.** The sandbox sets `push.negotiate=true` in the global git config and push negotiation is unsupported over the local file transport, so git prints that `fatal`, follows it with `warning: push negotiation failed; proceeding anyway with push`, and then **completes the push**: `* [new branch]      main -> main`, exit 0. The word `fatal` is what makes it read as a failed push; it is not one. Where a clean log matters, `git -c push.negotiate=false push origin main` removes the message entirely. Never conclude from it that the local transport is unavailable.
- **The real breakage is the bare repo's default HEAD.** `init.defaultBranch` is unset here, so `git init --bare` writes `ref: refs/heads/master` into HEAD. A seed that pushes `main` then leaves the bare repo's HEAD pointing at a ref that does not exist, and a clone of it warns `remote HEAD refers to nonexistent ref, unable to checkout` and checks nothing out — which reads as "the push did not land". It did: `git branch -a` in that clone lists `remotes/origin/main`, and **`git fetch origin main` succeeds**, so the behaviour a script of this shape is being tested against was never blocked at all. Create the fixture origin as `git init --bare -b main`, or set `git symbolic-ref HEAD refs/heads/main` inside it, and both symptoms go.

So the bare-origin recipe is sound and needs one flag. Committing in a non-bare seed and cloning *it* to make the fixture root also works and is a fine alternative, but it is not the fix for this: adopting it as the remedy would carry the wrong diagnosis forward and leave the next leg to meet the same `fatal` on the next local push it makes for any other reason.

(Measured first-hand on the refine surface, 2026-10-05, git 2.43.0: both symptoms reproduced exactly as reported; the push exited 0 both with `-b main` and with the default HEAD; `push.negotiate=false` removed the message; and `git fetch origin main` succeeded even against the broken-HEAD bare repo. **Premise unverified:** the delivery sandbox's own git config and git version were not read from here, so confirm `push.negotiate` and `init.defaultBranch` there before restating this as a per-surface fact — expected both as measured, since the global config is image-level. The originating observation is the APP-1284 QA leg on `assoc-one/aledpritchard-com` PR #38, head `7f54911`, 2026-10-03, which reported the push as having failed and the clone as having no `main`; the second half of that reading is the HEAD default above and the first half is the cosmetic message — APP-2012.)

### Reading a repo in an autonomous run — name the ref, never the bare path

The rule above governs writing from a clone; this governs reading one, and it is the quieter of the two. **Canon and any other repo state are read from `origin/main` explicitly — `git show origin/main:<path>` — never from a shared checkout's working tree.** A bare path resolves against the working tree, and a shared delivery checkout sits on whatever feature branch the last leg cut, so an instruction that names a path (`canon/skills/<artefact>/SKILL.md`) asks for *the file at that path* while the leg believes it is asking for *canon at that path*. The two differ exactly when the checkout is not on `main`, which on a publish run is most of the time.

```sh
git fetch origin main                                    # if the tracking ref may be stale
git show origin/main:canon/skills/<artefact>/SKILL.md     # canon, not whatever branch is checked out
git show origin/main:canon/tasks/<task-artefact>/SKILL.md # a task-* artefact lives under canon/tasks/
```

**And in `claude-ops` the canon path is `canon/`, not `.claude/`.** The repo's canon source moved out of `.claude/` on 2026-09-14 (APP-1457, APP-1458): skills, conventions, agent and operator profiles, core artefacts and routines sit at `canon/skills/<name>/SKILL.md`, a `task-*` artefact at `canon/tasks/<name>/SKILL.md`, and `.claude/` there holds only `settings.json`. So `.claude/skills/<artefact>/SKILL.md` is a **dead path in that repo rather than a synonym** for the new one, and a `git show` against it fails rather than returning something stale — the loud failure, for once, but only after the read has been attempted. Three claude-ops QA legs met it in one day through their dispatch briefs and lost a turn each. The `.claude/skills/<artefact-name>/SKILL.md` fallback in `core-operating-model`'s loader line is a **different thing and is correct**: it names the local Claude Code skills directory on the surface the session runs on, not a path in any repo — and `skill-review-pr`'s `/root/.claude/skills/synced/…` reference is the local deployed cache, also correct. Only a claim about the repo mirror's layout is wrong. (Instances: `assoc-one/claude-ops` PR #496 head `4902efa` and PR #498 head `7f9f5b9`, both 2026-10-21, plus the note's own reading of the repo's checked-in `CLAUDE.md` — APP-2506, the uncompleted remainder of APP-1692, whose fix reached `skill-ops-sync` alone. The paths, PR numbers and head SHAs are the filing legs' reports and are **unverified** here, no repo being readable from the authoring surface; the 2026-09-14 move is stated in live canon by `skill-ops-sync`, which is observed.)

Nothing in the result marks the difference: the read succeeds and returns an older answer, so a stale read is indistinguishable from a correct one and a wrong premise built on it survives every re-check that reads the same tree. This is the same family as a connector read taken through the wrong filter — the call does not fail, it answers the wrong question — and it is structural rather than a race: the checkout is behind by construction for the whole run, so the worktree isolation that answers a sibling leg branch-switching the shared `claude-ops` checkout under a live read (APP-1189) does not touch it. It also grows with the run: the more batches a publish run lands, the further `main` moves ahead of the branch the shared checkout holds, so the staleness is widest exactly while canon is being consulted most.

The exception is the read whose subject *is* a branch — a QA leg reading the head under review, or the site-render check pointing `CANON_DIR` at the checkout carrying the branch under test. There the working tree is the right source and `origin/main` is the wrong one. The rule is not "always `origin/main`"; it is **name the ref you mean**, because the unnamed default is the one that silently resolves to something else. The same applies to a delivery repo's own `CLAUDE.md` in a run that has switched branches — read it from the ref whose discipline you intend to follow.

**This fixes the branch-staleness half only.** Canon lives Claude-side in the skills store and `claude-ops` is a downstream mirror brought up to it afterwards by `skill-ops-sync` (`core-operating-model` *Changing canon*), so even `origin/main` is a publish cycle behind the store — a Cloud Routine is not confined to the mirror: a test routine with nothing attached found `skill-ops-sync` in its skills at the latest saved version, newer than the mirror's copy (reported from a 2026-10-09 test and not observed here — APP-2210). A routine can therefore read either copy. `git show origin/main:` gets a leg to the published rule rather than the current one; where the difference matters, say which of the two you have. (Worked case: the APP-1296 merge leg, 2026-09-10 — the shared `claude-ops` checkout sat on `claude/APP-1248`; "draft" occurred **0** times in the working tree's `skill-merge-pr/SKILL.md` and **3** times in `git show origin/main:` of the same path, including step 3's un-draft-at-the-gate clause. The driver concluded from the working-tree read that no draft rule existed and briefed five consecutive batches on that premise, which held because every re-check read the same stale copy; it broke only when one leg was told to read `origin/main`. APP-1317, recorded on APP-1312.)

## Reading CI / PR state in autonomous runs — never raw curl, always the MCP

Raw `curl` (or any direct HTTP) to the GitHub REST API is **blocked by the environment's egress proxy (403)**, even with `GH_TOKEN` set. The failure is quiet: `curl -s` swallows the empty 403 body, so a poll loop misreads "no data" as "no incomplete checks" and returns a false-positive "DONE" (worked case: a CI-wait on PR #49's Playwright check reported green when it had not run — APP-450). So:

- **Read all PR / CI / check state through the GitHub MCP** — `mcp__github__pull_request_read` (method `get_check_runs`) and the other `mcp__github__*` tools — never raw `curl`/`wget`/API-token HTTP. The MCP path is not subject to the egress block.
- **Before attributing a red check to the diff or to the base, establish that the job ran.** `runner_id: 0` with an empty `runner_name`, a job completing within a few seconds of creation, and a 404 on the log download together mean no runner was ever attached — an environment fact to report, not a failure to diagnose. Read the annotations before concluding a red check is unreadable: `output.title`, `output.summary` and `output.text` can all be null while `annotations_count` is non-zero, and the annotations endpoint returns the cause in plain English, which separates billing from quota from incident without inference. A failed log download is weak evidence on its own, because the download redirects to `results-receiver.actions.githubusercontent.com`, outside the egress allowlist — the same egress block as the raw-`curl` case above, not a signal about the job. The wrong readings are available and the most alarming is the most available: re-running indefinitely, "fixing" green code, or weakening an assertion to chase a green that was never achievable. (Worked cases: 16 of 16 jobs red in 3 seconds on `bot-trader`, and one check run on `claude-ops` PR `assoc-one/claude-ops#236` whose annotation read "The job was not started because recent account payments have failed" — APP-1414, APP-1413.)
- **For a bounded CI-wait, alternate an MCP check with a time-based bash delay** — `until [ $(date +%s) -ge $end ]; do sleep N; done` for the wait window, re-querying check state via the MCP each iteration. Do **not** gate the loop on a network call that can itself be blocked (that is what produced the false green), and do **not** rely on a bare `sleep N` — the harness blocks it, so a condition-based delay whose condition is `date` (not the network) is the working pattern.
- **A backgrounded `sleep` does not wait, so a loop paced by one has no clock at all.** `Bash` with `run_in_background: true` returns as soon as the command is *started*, not when it finishes: the sleep runs detached and the poll loop proceeds immediately, so a sequence of polls spanning seconds is read by the run as spanning minutes. The failure is the quiet kind — every poll succeeds and every reading is truthful, and only the run's belief about the interval between them is false, so the more carefully the run compares against sibling durations the more confident the wrong conclusion becomes. To actually wait, block in the foreground with the `date`-driven delay above, or await the background task's own completion notification before polling again. Never pace a wait — CI, a deploy, a preview build, a rate limit — on a backgrounded delay. (Worked case: `assoc-one/firmup-operator` PR #26 / A1-384, 2026-09-08 — a CI wait paced by a backgrounded `sleep` read a ~90-second-old run as stuck for 25 minutes and cancelled it; the re-run concluded green in 79 seconds, in line with the six preceding runs on that repo. APP-1193.)
- **State the session's tool surface, so its limits are readable rather than discovered by failing.** In the delivery/session sandbox, `gh` is **absent on some surfaces, present-but-token-limited and proxy-path-restricted on others, and a set `GITHUB_TOKEN` may be a placeholder** — never assumed either way; the three measured states, and the test that separates them, are stated once under *GitHub MCP tools*. The GitHub MCP is the reliable route for PR and CI state, and egress is HTTPS-only (the raw-`curl` 403 above is that egress block; see also *In the delivery sandbox…* under *GitHub MCP tools*). Three different failures hide under one word, and calling them all absence costs a run either a wasted attempt or a wrongly abandoned one: where `gh` is installed its token can fail `gh auth status` while a repo-scoped REST read still returns data, so reading that self-report as the capability abandons a route that answers — the test, and the axes it separates, are stated once under *GitHub MCP tools* (measured on the Pulse cloud surface 2026-10-23); the documented `gh pr checks` watch pattern — pulled in by the Monitor tool's own examples and by habit, **not** by canon — returns nothing useful whatever the credential does, because it goes through GraphQL rather than because the token is bad (APP-935); the GraphQL transport is refused outright, which kills `gh pr comment` (APP-1461) and `gh repo clone` (APP-1353); and a REST call on an allowed `repos/{owner}/{repo}/...` path can still be rewritten onto a blocked one by a client-side flag. That last case is the one that half-works: **on Actions run-listing endpoints, page explicitly with `page=N` rather than `--paginate`.** Page 1 succeeds; `--paginate` then follows GitHub's `Link:` header, which for these endpoints gives the numeric-ID form `repositories/{id}/actions/...`, and the proxy refuses that path with a 403 naming it. The failure is invisible until a repo has more than one page of history, and then it hits every leg that needs run history rather than the latest run — cost analysis, flake hunting, "has this spec ever been green", the `present-and-concluded` checks `skill-merge-pr` and `skill-review-pr` both make. Request pages explicitly and stitch them. State this precisely rather than as a ban on `--paginate`: it remains fine on `.../runs/<run_id>/jobs`, whose `Link` header stays in `repos/...` form and which was used repeatedly in the same run without trouble. (Worked case: listing 163 CI runs on `assoc-one/bot-trader` — the first page returned, the second was refused with *"Numeric-ID repository paths (repositories/{id}/...) are not supported through this proxy"* — APP-1482.)
- **A poll loop's failure branch must emit, never `continue` silently.** A CI-read poll that fails must echo a failure and sleep — `… || { echo "POLL FAILED: $?"; sleep N; }` — never swallow the error and loop on, because a blind monitor is indistinguishable from a running one and a silent failure passes as "still waiting" indefinitely. This is the same family as the APP-450 `curl -s` case above, where a swallowed 403 body read as "checks passed" — the second instance of that exact family, promoted here from worked case to stated rule. (Worked case: APP-917 exec leg, `assoc-one/bot-trader` PR #32 — two Monitor windows burned emitting nothing — APP-935.)

- **Three distinct causes present as one symptom at the call site, so a watch loop names which one it hit and stops.** "Every documented CI-watch pattern silently no-ops" has three causes, and from inside the loop they are indistinguishable: an **absent binary** (`gh: command not found`, APP-935); a **credential that fails `gh auth status` while repo-scoped REST still returns data** (measured on the Pulse cloud surface 2026-10-23 — *GitHub MCP tools*); and a **transport or attachment refusal** (a GraphQL 403, or a repo-scoped 403 naming `add_repo`). The `|| { sleep 30; continue; }` shape this section's own watch pattern uses swallows all three identically, so the loop reports "pending" for a run that is green, for a run it was never able to reach, and for a repo it is not attached to — three different conclusions behind one word, with nothing in the loop's output separating them. So a watch loop **classifies the failure before it decides to wait**: capture the exit status and the stderr rather than discarding them, classify by the signature each cause prints, echo the classification, and **stop** on the first and third classes, which no amount of waiting clears. Looping is an assertion that waiting will help, and it is warranted only where a read returned data and that data showed the run unconcluded. The bullet above says a failure must not be silent; this one says a named failure must not be looped on. **The credential and transport signatures are observed on the Pulse cloud surface on 2026-10-23; the absent-binary signature is canon's existing dated observation. The delivery sandbox is not readable from here and none of the three is asserted of it.**

- **`get_workflow_run_usage` returns a structural zero on this account — derive real per-run Actions cost from job timestamps, never from the billing summary.** `mcp__github__actions_get` `get_workflow_run_usage` is the obvious tool for a per-run minute figure and it answers, with `billable.UBUNTU.total_ms: 0` and `duration_ms: 0` on every job, on completed runs that plainly consumed minutes. This is GitHub's 2023-onward deprecation of the classic workflow-run-usage billing endpoint rather than an MCP fault, but the response carries no signal that the field is dead, so the zero is indistinguishable from a genuine zero — the same family as the swallowed `curl -s` 403 above and the `runner_id: 0` case, where the instrument's silence reads as the measurement. It is the more dangerous member of that family because the wrong answer flatters: a run that reports "0 billed minutes" on a ticket about runaway Actions spend sounds like good news. The real figure comes from `list_workflow_jobs`: take each job's `started_at` against its `completed_at`, round each job up to the next whole minute (GitHub's own per-job billing rule), sum, and multiply by the runner-label rate — 1x Linux, 2x Windows, 10x macOS. The tell that prompted the check was the zeros being *identically* zero across two separate runs rather than plausibly small; treat an exactly-zero billable field as an instrument reading, not a measurement. (Worked case: a CI-cost ticket on `assoc-one/bot-trader` PR #57 whose acceptance criterion was cost measured rather than estimated; `total_ms: 0` across all 16 jobs, reproduced identically on two further completed runs, and the per-run figure reconstructed from job timestamps from first principles — APP-1481.)
- **Check runs and commit statuses are two different surfaces — read both, or you will report a gate green that has not cleared.** GitHub Actions jobs are **check runs** (`get_check_runs`); a third-party app posts a **commit status** (`get_status`). They do not appear in each other's results. On a Chromatic repo the `chromatic` *action* is a check run and Chromatic's *"UI Tests"* verdict is a commit status, so "all checks green" read from `get_check_runs` alone says nothing about whether the baselines have been accepted. Read both before declaring CI clear, and treat `mergeable_state: unstable` on an all-green check-run read as a prompt to go and look at the statuses. On `get_status`, read `total_count` before trusting the combined `state`: GitHub reports the combined state of an *empty* status set as `pending`, so `total_count: 0` means **no status gate exists on this repo at all**, not a real gate that has yet to conclude — only `total_count > 0` with a non-success `state` is a pending gate to wait on or route. Reading an empty set as pending false-stops a merge on every repo with no status app (bot-trader, claude-ops, agents-site); the Chromatic repo (meirionpritchard-com) is the exception the read-both guidance was written for, and the one place a real `UI Tests` status actually lives. The failure direction is the safe one — a false-stop, never a false-green — but it still stalls a clean merge, so branch on `total_count` rather than on `state` alone. (Worked case: A1-299 / `meirionpritchard-com` PR #87, 2026-07-31 — the first QA pass reported "chromatic green" from the check run and missed the pending `UI Tests` status; the re-review caught it — APP-734. Empty-status-set case: APP-973.)
- **And whether a pending status *gates* the merge is a repo configuration — read it from the repo, never inferred from `mergeable_state` and never from what previous pull requests got away with.** The bullet above says read both surfaces; it does not say which of the things read is allowed to hold a merge. A green check run and a pending commit status coexist on one head routinely, and whether that status is required is a property of the branch's ruleset rather than of the pull request. The direct reads are `gh api repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks` and, for the ruleset path these repos are actually on (*Human-only — making it required*), `gh api repos/{owner}/{repo}/rulesets` plus the ruleset's own id. **A read missing from a session's GitHub MCP roster is not a read that does not exist**: the GitHub MCP tools expose no branch-protection method at all, and `gh` is present on the fleet's surfaces, so a leg that finds no MCP tool takes the `gh` read rather than concluding the instrument is unavailable — a false unavailable closes a working route and leaves the judgement resting on precedent. Where the `gh` read itself returns 403 with a repo-attachment message, the leg records the probe and its response, names the attachment as the gate, and only then takes the inference below as a **flagged** fallback. **The fallback and its premise:** `mergeable_state: "unstable"` is widely read as *mergeable with a non-required status pending or failing*, against `"blocked"` for an unmet required check — GitHub documents neither value, so that mapping is **unverified** and a merge resting on it says so in the merge record. Precedent from recently merged pull requests substitutes for neither read: it establishes what was not enforced then, under a configuration that can have changed since, and it is unavailable on a repo's first pull request or straight after a ruleset edit. (Worked case: the APP-2777 merge leg on `assoc-one/claude-ops` PR #588, 2026-10-30, read `unstable` with both Actions check runs `success` and the classic `Vercel` context — the Vercel app's deployment status, distinct from the `Vercel Preview Comments` check run — still pending and not advancing across a ~60s poll, and proceeded by pulling the five preceding merged pull requests and reasoning from the undocumented mapping. Second time a merge leg has reasoned about `mergeable_state` with no instrument, after APP-582 and APP-1079 did it for `"unknown"` and added the `merge-tree` substitution to `skill-merge-pr`. The pull request, its statuses and the poll are the filing leg's **report**, no repo being readable from the authoring surface. **Observed** on the refine surface: `gh` 2.89.0 at `/usr/local/bin/gh` authenticates as `assoc-one` on `gh api user`, and `branches/main/protection`, `branches/main/protection/required_status_checks` and `rulesets` on `assoc-one/claude-ops` each returned HTTP 403 naming repo attachment as the remedy — which establishes the endpoints as reachable by route and gated by attachment, not absent. APP-2783.)
- **For *liveness* — whether a job has actually concluded — poll `actions_list` `list_workflow_jobs` on the run id; `get_check_runs` and `get_workflow_job` are cached and non-authoritative for this.** Both `mcp__github__pull_request_read` `get_check_runs` and `mcp__github__actions_get` `get_workflow_job` serve a stale `in_progress` for **20+ minutes** after a job has actually finished green, and they lie in the *same* way — so cross-checking one against the other (the obvious move, since `get_workflow_job` returns per-step detail and *looks* authoritative) learns nothing and reads as a genuine hang. `list_workflow_jobs` on the run id is the **least stale** of the three, returns all the run's jobs in one call, and is cheaper than polling check runs — but it is not fresh, and **no GitHub status surface here is trusted fresh.** It too serves a cached snapshot: on one feasibility-loop run it returned a byte-identical `in_progress` reading across nine polls spanning more than an hour on a job that had in fact completed green about two minutes after dispatch, and only an unrelated background wait shook a true read loose. So bound the wait by arithmetic rather than by the surface's own say-so: compute elapsed time from the run's `run_started_at` against the current clock, compare it against the workflow's known median duration, and treat **two identical consecutive reads as possibly cached** rather than as confirmation — identical is the tell, the same reasoning as the identically-zero billable fields above. Where the arithmetic says a run should long since have finished and the surface still says `in_progress`, the surface is the thing in doubt. Do not cancel or re-dispatch on a stale read: a re-dispatch spends real budget on a run that already succeeded and, on a workflow that commits its own output, risks colliding with a run mid-commit. Whether the staleness lives in the MCP server, the proxy or GitHub itself is not established. This **narrows** the "read both surfaces" rule above, it does not delete it: keep `get_check_runs` as the **enumeration** read (check names, job ids) and as the **third-party-gate / commit-status** read (the Chromatic `UI Tests` case), but never as the **liveness** read. Reach for `get_job_logs` **only to read a failure**, never to establish whether a job finished — it is a per-job wall of text answering a yes/no question. And never read `get_status` as liveness on an Actions-backed repo: it returns `state: pending, total_count: 0` throughout because the repo reports as check runs, not commit statuses — a dead end a run will otherwise try. A liveness gate reading a stale surface fails *closed* (it declines to act on a green run), which is safe but reproduces the very stall it is meant to catch. (Worked cases, both `assoc-one/bot-trader`, the two pure-Python `research/*` suites `fx-carry-study` and `fx-momentum-study`: PR #34 head `a90244d` 2026-08-15, ~8 min stale; PR #35 run `31894544260`, **>20 min** stale — `218 passed` / `63 passed` and completed ~16:06 while `get_check_runs` and `get_workflow_job` both read `in_progress` past 16:27, and only `list_workflow_jobs` read `completed`/`success` — APP-938.)
- **An elapsed-duration claim about a CI job is computed from the job's own `started_at` against the current time, and states both.** *"Running 6m so far (started 14:26:02, now 14:32:07)"* is checkable; *"still running after 60+ minutes"* is not, and cannot be challenged without redoing the work. A duration reads as objective, so a downstream reader treats it as measured rather than impressionistic — and a hand-polling agent with no timer conflates its own session time with the job's. The refusal to self-attest an unconcluded gate is correct and unchanged; only the arithmetic is added. Keep this to the CI case. (Worked case: A1-304 / `meirionpritchard-com` PR #107, 2026-08-16 — a hand-off comment reported a "60+ minute hang" at 14:32:07 on a job that started 14:26:02 and concluded green at 14:36:15; Prism spent much of its review disproving the premise — APP-1018.) **And the same evidence gates the action, not only the sentence: cancelling or re-running a job needs a duration the API itself supports.** "It has been N minutes" is a claim with a source like any other, and a run has no internal timer entitled to stand behind it — so read `run_started_at` / `updated_at` off the workflow run and compare against the current time from the same source before calling a job slow, stalled or stuck, and before writing to it. A cancel is a write to someone else's system: harmless on a fast unmetered pipeline, not harmless on a metered one or a deploy workflow. (Second worked case: PR #26 / A1-384, 2026-09-08 — a healthy 90-second-old run cancelled and re-run on an elapsed figure the run had estimated rather than read, and the hand-off comment carried a fabricated "Actions capacity condition" with the CI box unticked on that basis; caught only because the GitHub API returns absolute timestamps and one of them sat *after* a comment the run had already written. APP-1193.)

## A CI run's duration is not a diagnosis — read the failing leg's own log, and do not write a ceiling a repo does not have

A long CI run measures how long the run took and nothing else. It is not evidence for any named mechanism, and a threshold built from a handful of slow runs is a correlation with a number attached: it survives exactly as long as nobody reads the timestamps. **So a slow or failing run's cause is established from the failing leg's own log — the first failure's timestamp against the step's start — never from the run's length, and never from where that length sits against a remembered band.** Where the log puts the failure a minute into the step, no theory about what the dev server does twenty minutes in is available, whatever the wall clock says.

Two things follow:

- **A suite whose runtime is genuinely variable gets a stated band and a per-leg timeout, never a ceiling.** Where the contributing causes are non-exhaustive — media specs, upstream egress variance, ordinary runner variance — an absolute ceiling is a claim the suite cannot keep, and a leg that reads a run beyond it as broken cancels healthy work. Bound a wait by `run_started_at` arithmetic against the workflow's **known median** (*Reading CI / PR state in autonomous runs*), and bound the job in the workflow with `timeout-minutes` per leg, which fails a genuine hang loudly instead of leaving a leg to judge it.
- **The band is repo-lane; the shape of it is canon.** A measured range belongs in that repo's own `CLAUDE.md`, restated with the date and the matrix it was measured on. What belongs here is that it is a band and not a ceiling, and that a duration never carries a cause. Same split, and the same reason, as the healthy-run invariant above: a figure copied forward goes stale while the shape does not.

(Worked case: `assoc-one/meirionpritchard-com` PR #206 / A1-554, 2026-09-30 — the single `playwright` job ran anywhere from roughly 20 to 75 minutes with no test failures behind the slow runs, and a "~23-minute Turbopack dev-server corruption" threshold was built from two data points and carried into A1-567 as a theory. Timestamped log analysis put the same error roughly one minute into the test step, so the threshold described nothing; the failure's actual cause was the moved base in *A `pull_request` run tests the merge with `main`*. A1-567 / PR #211 then split the job into a desktop/tablet/mobile matrix with an aggregate `playwright` check and a 30-minute per-leg timeout, and recorded the no-fixed-ceiling note in the repo's `CLAUDE.md`. Confirm both against `origin/main:CLAUDE.md` and `origin/main:.github/workflows/playwright.yml` before writing a per-repo claim; expected a "no fixed runtime ceiling" heading and three legs under one aggregate check. All runtime figures, the matrix and the repo-doc note are reported from those runs and not observed — no repo is readable from the refine surface; that flag covers those three premises. APP-1898.)

## Reading the GitHub MCP safely — read volume and parameter naming

The delivery loop reads CI on every merge leg, and `skill-merge-pr`'s CI-wait polls the GitHub MCP in a loop, so a read that overflows or errors on its first call fails the leg at the moment it depends on it. This is the GitHub-side counterpart of `convention-linear`'s *Reading Linear safely* rules — the same silent-failure family, learned per run until written down.

- **One scoping qualifier per `search/issues` query — `org:` and `repo:` in the same `q` OR together, so a per-repo count silently returns the org-wide total.** `gh api -X GET search/issues -f q='org:assoc-one repo:assoc-one/claude-ops is:pr is:merged'` returned **1367** — exactly what `q='org:assoc-one is:pr is:merged'` returns on its own, because the `repo:` constraint is discarded with no error and no warning. The per-repo figure is `q='repo:assoc-one/claude-ops is:pr is:merged'` alone: **674**. Isolate the remainder with a negated qualifier — `q='org:assoc-one -repo:assoc-one/claude-ops is:pr is:merged'` returned **693**, and 674 + 693 = 1367. That sum is the discipline the trap wants: **before a count is published, cross-check it with a second query whose parts sum to the whole.** A wrong figure here is plausible rather than absurd, so nothing in the response flags it. There is no enumeration route around it either — `orgs/{org}/repos` is refused on a session-bound surface (HTTP 403, *"sessions are bound to their configured repositories"*), so per-repo `search/issues` counts are the only way to a per-repo figure (`APP-3042`).
- **Default `minimal_output: true` on `actions_list`, and pass `perPage` small.** A full run object embeds two `repository` blobs (each ~40 URL-template fields) plus `actor` and `triggering_actor`, so the payload is ~99% boilerplate: `list_workflow_runs(branch, perPage: 5)` returned **64,692 characters on one line** and was refused by the tool limit. `minimal_output: true` returns the same call cleanly. This is the exact analogue of the Linear "returns every ticket's full description" overflow, and wants the same treatment — minimal output plus a small page — rather than a refused call, a persisted-file write and a parse to recover. (APP-708.)
- **To verify a *specific commit's* workflow run, don't page `actions_list` — read the commit's checks.** `actions_list`'s `workflow_runs_filter` offers `actor`, `branch`, `event`, `status` — but **no `head_sha`**, so the one field identifying *this* merge's run cannot be filtered on, and a leg confirming "did `canon-publish.yml` fire and pass on merge commit `<sha>`?" is forced to fetch a page and scan it. That page is heavy even bounded: `perPage: 5` returned **194,113 characters** on 2026-08-13 because each run carries the full `repository`/`head_repository` payloads (~35KB apiece), and where `minimal_output` is not honoured on the call there is no lever left to shrink it. So for a specific-commit verification prefer **`mcp__github__get_commit` on the merge sha → read its check runs** (a push-triggered workflow surfaces there), or `actions_list` with **`perPage: 1`** — a two-field question (does a run exist at this sha, and what is its conclusion) answered by a ~40KB read instead of a 194KB page. Reserve the paged `actions_list` for when you genuinely need the *list*, not one commit's result. (APP-850; sibling instrument gap to `pull_request_read get`'s missing `merge_commit_sha`, APP-846.)
- **When a read overflows anyway, the sanctioned recovery is spill-and-slice, not re-issue.** Where the call cannot be narrowed below the tool-result cap (a `head_sha`-less `actions_list`, a `minimal_output`-less `get_files`), the result is persisted to a file; recover the handful of fields needed with a `python3 -c 'import json,sys; d=json.load(open(path)); …'` slice rather than re-issuing the call at a different shape and overflowing again. This is the GitHub-side analogue of `convention-linear`'s `get_document` spill recovery — read the saved payload, do not retry blind. (APP-850, APP-790.)
- **Spill-and-slice recovers fields, never a byte-exact blob — a digest or a byte count reads through a clone.** The rule above is for lifting a handful of *fields* out of a refused result, and that is its whole scope. `mcp__github__get_file_contents` on a file over the inline cap does not spill the raw blob: the spilled text is wrapped in a tool-result-shaped prefix — a line of the form `[Resource from github at repo://<owner>/<repo>/sha/<sha>/contents/<path>] ---` ahead of where the content begins — so hand-parsing that boundary and then hashing or counting what follows measures the reconstruction, not the artefact, and the tool's own output carries no warning that the two differ. The error is silent and it is confident: a wrong byte count and a wrong `sha256` look exactly like a right one. **So where the question is byte-exactness — does `origin/main` already carry these bytes, what is this path's current digest, is the artefact genuinely behind — the answer comes from a full clone and `git show origin/main:<path>`, never from `get_file_contents` at any size.** This is the GitHub-side instance of the rule `skill-build-ticket` already states for the other connector — *"An inline attachment result is a reproduction, not the artefact"* — the same *what*, a different connector, and it bites on exactly the leg that needs it most: the execution-time "verify genuinely behind" check on an ops-sync publish ticket, where the artefacts are routinely at or above the cap by nature. Where the figure is only being *reported* rather than compared, say which route produced it. (Worked case: the `APP-2691` exec leg, 2026-10-28, read a canon artefact off `origin/main` through the spill to compare its byte count and digest against the ticket's declared values, hand-parsed the wrapper, and produced a byte count a few bytes short of the truth and an entirely different `sha256`; a real clone and `git show origin/main:<path>` moments later returned figures matching the ticket's own. The discrepancy surfaced only because the ticket's acceptance criteria forced a second, independent verification route — had the hand-parsed figure been trusted it would have been a false digest claim in a PR body. **The byte counts, both digests and the exact wrapper shape are the filing leg's report and are unverified here — no repo ref is readable from the authoring surface, so none of them was re-derived. The hazard class does not rest on them.** APP-2720.)
- **The parameter is `resource_id`, not the natural `run_id`.** `actions_get(method: "get_workflow_run", run_id: …)` and `list_workflow_jobs(run_id: …)` both fail with `missing required parameter: resource_id`; the generically-named `resource_id` is the parameter regardless of which method is selected. Low severity, high recurrence — every run that inspects CI hits it.
- **`pull_request_read`'s `get_files` embeds every file's patch and has no `minimal_output` — on a leg that already has the repo checked out, read the diff with local `git`.** The per-file `patch` blobs mean even a modest PR overflows: `get_files` on a +884/−140, 10-file PR returned **69,849 characters on one line** and was refused, spilling to a file that then needs an out-of-band character-range parse. Unlike `actions_list`, `pull_request_read` exposes no `minimal_output` to suppress them, so the minimal-output remedy above does not transfer. The exec and QA legs run with the repo cloned on the PR's head commit, so `git diff origin/main...HEAD` (optionally per-path) reads the same diff with no token ceiling, no pagination and no saved-file parse — confirm `git rev-parse HEAD` matches the PR's head SHA first (QA does this anyway for its dedup key). **Read `git diff --stat origin/main...HEAD` first, and exclude lockfiles and generated artefacts from the content read unless the lockfile is the subject of review** — `git diff origin/main...HEAD -- . ':!package-lock.json' ':!*.lock'` — because a scaffold or dependency PR is mostly lockfile and overflows even the local read (`Luna#1`: 7,272 additions, ~93% `package-lock.json`, 260k characters refused — APP-1059). Reserve the MCP file read for a surface with no checkout. High recurrence — QA hits it on essentially every non-trivial PR. (APP-788.)
- **A large CI log overflows the tool-result budget too — slice it from disk rather than re-reading.** A 139k-character CI failure log exceeded the limit and had to be sliced out-of-band from the persisted file. Reading CI failures is routine for the merge and QA legs, so treat a refused log read the same way as the overflow reads above: take the saved payload and read the failing range rather than re-issuing the call. (APP-790.)
- **`get_job_logs` is tail-anchored only — read a mid-transcript block by a stated ladder, never by re-issuing at guessed sizes.** The tool exposes `tail_lines` and nothing else: no offset, no line range, no search. A block that is not near the end of a long transcript is reached by starting at a small tail (~200 lines), doubling until the block is in view, and stopping at the tool-result cap — at which point the sanctioned recovery is the spill-and-slice rule above, never another blind re-fetch. This bites hardest on `bot-trader`, whose probe workflows deliberately print their evidence into the log, so a QA or exec leg reading a probe result is doing the mid-transcript read by design. The durable remedy for that repo is in the repo lane, not here: a workflow whose log is the acceptance artefact prints a tail-reachable summary block or writes a committed artefact. (Worked case: two legs of the 2026-09-02 `bot-trader` run each re-fetched progressively larger tails to reach one block — APP-1078.)

## GitHub App permissions required

For exec and merge to function on a repo, the Claude Code GitHub App must have:
- **Contents: read & write** — required for push
- **Pull requests: read & write** — required for PR creation and merge

Read-only causes a 403 on push, which is a Blocked outcome for the exec leg.

## Standing up CI on a repo

Adding a workflow file is not adding CI. A check that runs but gates nothing reads as green and verifies nothing — the false-green class `skill-merge-pr` names — and the standing definition-of-done box *"CI present, concluded, green"* is only genuinely satisfiable where a **required** check exists. So the sequence has two halves, and the second one is a human action every time.

**Agent-doable — the workflow file.**

1. Add `.github/workflows/ci.yml` running the repo's **real** scripts (its own `lint`, `type-check`, `test`, `build`), not a generic template.
2. Pin Node to the major in the repo's `engines` field.
3. `npm install` before the first script of any kind (see *Fresh clones*).
4. **Where any workflow in the repo commits to `main` with the workflow's own `GITHUB_TOKEN` — a scheduled data capture, a generated report — add a trigger a bot push cannot silence.** A push made with `GITHUB_TOKEN` does not trigger workflow runs, so on such a repo CI never runs on those commits and `main` can go red with nothing reporting it; the next PR opened inherits the red and every merge on the repo halts. Add `schedule:` (zero-credential; daily is enough) or `workflow_run` to `ci.yml` at the point CI is stood up, so it is not rediscovered per repo. (Worked case: `bot-trader` — a bot-pushed funding-data commit broke `backfill.test.ts` on 2026-08-21; the last CI run on `main` was 2026-08-18; discovered by APP-679's PR five days later as the first PR opened since — APP-1055, APP-1056.)
5. **Prove it green on its own PR before treating the ticket as done — and prove it can go red.** Green alone is a one-sided proof: a workflow that cannot fail is green too, and a check that gates nothing reads exactly like a check that gates everything. Do it in three commits on the ticket's own PR branch — the passing workflow, a deliberate break, then a `git revert` of the break — so the head that merges is green and the proof commits squash away on merge. Two details carry the proof. **Break the substantive step, not the install:** a failed install shows only that the runner runs, so break the thing the check exists to catch (on `ds-poc`, a type error that passes `eslint` and fails `tsc -b`, because `typescript-eslint`'s recommended config is not type-checked — breaking the install there would have proved nothing about the type gate). **Read the failing job's log and confirm the failure message is the intended one:** a red for the wrong reason — a workflow syntax error, a missing dependency, a runner fault — proves nothing about the check. This composes with the `workflow_dispatch` limitation below: a brand-new workflow is not registered on the default branch, so `pull_request` is the only pre-merge route to either half of the proof (APP-632). (Worked case: the APP-1125 delivery-loop run, 2026-09-07, standing CI up across four repos with no PR-triggered CI — `ds-poc`, `portal`, `gtd`, `careeros-web` — where the ticket author wrote the red half by hand because canon stopped at green, and the run then invented the mechanics with no canon to follow — APP-1146.)

**Human-only — making it required.** The GitHub App's scope does not carry repo-admin, so no agent can make a check required. GitHub has migrated from branch-protection rules to **rulesets**; the old *Settings → Branches → branch protection rule* path no longer exists on these repos and instructions describing it are stale. The live flow, verified 2026-07-20:

1. Repo → **Settings** → **Rules** → **Rulesets** → **Add branch ruleset**
2. **Ruleset Name** — name it
3. **Enforcement status** → **Active**
4. **Target branches** → **Add target** → **Include default branch**
5. Rules → tick **Require status checks to pass**
6. **Add checks** → search the check's job name → select it
7. **Create**

Two things to know before writing this instruction for the operator:

- **Order matters, and the reason is invisible.** A check appears in the *Add checks* search only once it has run at least once. Workflow first, ruleset second — requiring a check that has never run finds nothing, which reads as a broken UI rather than an ordering problem.
- **Tick the status-check rule only.** Signed commits, linear history and required reviews each add friction to the agent delivery loop and none is wanted by default. This is the default, not a judgement call.

**Where the human half lives depends on whether enforcement is available, and today it is not.**

- **While required checks are soft-gated (today — see the section below), do not file a per-repo required-check leaf at all.** The repo is added as a line to the single on-upgrade checklist on **A1-313**, and that checklist is the only place this work exists. This is a structural rule, not a preference: the leaf is not filed, so there is nothing to park.
- **Once enforcement is available**, the required-check step is filed as a separate `OPS:` leaf — `human`, assigned to Aled — rather than left as an acceptance criterion on the build ticket that nothing in the loop can tick. That is what stops it arriving as a surprise at review, and stops the bounded DoD waiver becoming the path of least resistance on every new repo. A waiver routes around a missing instrument; it never replaces one. (APP-619, from `A1-222` on `assoc-one/firmup`.)

### Billed minutes are part of standing up or changing a workflow — cancel superseded runs by default, and state the cost of a change that adds them

A workflow's cost is a property of the workflow, settled when it is written, and the estate has now twice found it by hitting the Actions budget instead. Two rules, both agent-doable:

1. **Every `pull_request` workflow carries a concurrency group keyed on the ref, with `cancel-in-progress: true`.** `concurrency: { group: "${{ github.workflow }}-${{ github.ref }}", cancel-in-progress: true }` is the default on any workflow triggered by `pull_request`. Without it every push during a debug stretch bills a full run alongside the one it has just superseded, and on a long suite that is the largest avoidable line in the bill. Two exclusions: a workflow on `main` or a tag, where the superseded run is still the record of a commit that shipped; and a workflow that commits its own output, where a cancellation mid-commit costs more than the minutes. Note the interaction with an enforced required check — a cancelled run is not a passing run, so the gate is satisfied by the run that survives, which is the one on the head being merged.
2. **A ticket that adds matrix legs, or materially lengthens a workflow, states its billed-minute impact as a criterion.** Per-PR minutes before and after, derived from job timestamps rather than from the billing summary, which returns a structural zero on this account (*Reading CI / PR state in autonomous runs*). A matrix split is not free in minutes even where it is a clear win in wall clock, because setup runs once per leg. Word the criterion as the measured property — per-PR billed minutes at the head, before and after, each job rounded up — so it is tickable from a run rather than from an estimate (`convention-ticket`, *Acceptance criteria vs definition of done*). Speed and cost are both criteria, or the trade is not being made, only taken.

The budget itself — whether it warns before it stops, and where the ceiling should sit — is the Owner's and is already owned by APP-1456. It is named here and not re-filed.

(Worked cases: A1-567 on `assoc-one/meirionpritchard-com`, merged 2026-09-30 — the Playwright job was split into a three-leg matrix, specified and accepted purely on speed, and the rise in billed minutes per PR surfaced only mid-build as the org hit its budget. Neither that repo nor `bot-trader` ran `cancel-in-progress`, so roughly three days of 20–75-minute Playwright runs billed in full against the runs they replaced, driving the 2026-09-30 budget stop. `bot-trader`'s 16-job matrix had already reached 57% of estate Actions spend and caused the 2026-09-13 runner-allocation outage — APP-1455, APP-1413. The repo-side remedy for meirionpritchard-com is A1-577. Every workflow-content and spend figure here is reported from those tickets and not observed — no repo is readable from the refine surface; that flag covers the absence of `concurrency` in both repos' workflows and the per-PR minute figures. APP-1902.)

### A `pull_request` trigger filtered to `main` leaves a stacked PR ungated — never merge a stack upward to acquire a gate

A workflow triggered `on: pull_request` with a `branches:` filter naming the default branch runs on PRs **into** that branch and on no others. A PR whose base is another PR's head — a stack — therefore gets no lint, no type-check, no test and no build leg. Its only checks are the base-agnostic ones, typically a deploy preview, so the check list reads like a short CI rather than an absent one, and nothing on the PR says the difference. **The gate is a property of the base branch, not of the change.** Two rules follow, and the second is the expensive one:

1. **When standing up or changing CI, do not filter the `pull_request` trigger by base branch.** An unfiltered `pull_request:` trigger is the default (*Standing up CI on a repo*, agent-doable step 1); it costs nothing the ref-keyed `concurrency` group does not already contain (*Billed minutes are part of standing up or changing a workflow*), and it is what makes a stack reviewable one change at a time. Where a filter is genuinely wanted, it names every base a PR is actually opened against, not only the default branch.
2. **Never merge a stacked PR into its base PR in order to get it gated.** It does gate the code — once, folded into the base PR's combined diff — and it pays for that by destroying the per-change gate and the review boundary together: the reviewed PR now carries a diff nobody reviewed on its own, and the stacked change has no run of its own for a definition-of-done box to cite. Where the trigger cannot be fixed in the same pass, the two honest routes are to re-base the stacked PR onto the default branch so it gets a real run, or to state in the PR body that the change is gated only through the base PR and name that PR's run. Either is reportable; a silent upward merge is not, because it leaves a merged tree whose evidence trail says a gate ran on a diff it never saw.

So a stacked PR's check list is read **before** the stack is treated as gated, in the same breath as reading `mergeable_state` (*A `pull_request` run tests the merge with `main`*): a short check list on a stacked PR is this rule, not a slow platform and not a flake. Note the interaction with an enforced required check — a required status configured on the default branch's ruleset is never evaluated on a PR that does not target that branch (*Required checks are enforceable per repo on Pro*), so "required check green" is also a statement about the base, and a stack satisfies it only at the point the base PR merges.

(Worked case: `assoc-one/agents-site`, 2026-10-02 — a cloud session was assigned branch `claude/fervent-cannon-00q3zn` while the reviewed PR sat on `claude/a1-452`, so follow-up work opened as a second PR with base `claude/a1-452`. That PR carried only the Vercel preview check, and its changes were gated solely by being merged into the base PR; until then the only evidence was local runs. Unverified — no repo access from this refine surface: the specific claim that `agents-site`'s CI workflow filters its `pull_request` trigger to `main` is read from that repo's `CLAUDE.md` description and from the stacked PR's observed check list, not from `.github/workflows/ci.yml` itself, and the branch and PR identifiers are reported from the note. The general rule above does not rest on that premise; the repo-side correction is filed as a repo-lane ticket. APP-2037.)

### Required checks are enforceable per repo on Pro — Option B's condition was met on 2026-09-23

GitHub's Rulesets page on a private repo reads *"Your rulesets won't be enforced on this private repository until you move to GitHub Team organization account."* Team is an organisation plan and `assoc-one` is a personal account, so the milestone that message names **cannot occur** — a gate written against it reads as *not yet* forever rather than as *wrong*. The cost is charged, not hypothetical: APP-1438 was raised, triaged, sized and worked as *"move the assoc-one GitHub org to a paid plan (Team)"*, and the error was caught only at the moment of purchase with the Owner about to buy on the wrong page (APP-1451). The personal-account equivalent is **Pro**, taken 2026-09-14. GitHub documents required status checks as available on Pro for private repositories, but at least one community report describes a Pro account still being refused enforcement — possibly the newer rulesets feature rather than classic branch protection, unconfirmed. So **the condition is an observation, not a plan name: enforcement counts as available once a required check is seen to actually block a merge on a private repo, and never because the account reads Pro.** Until that observation exists, every "make the check required" ruleset step above is a **no-op** on these repos: it reads as done while gating nothing, which is the false-green class in reverse.

**That observation now exists, so the gate is open.** On 2026-09-23 a branch ruleset was added on `assoc-one/meirionpritchard-com` (`main`, *Require status checks to pass* → the `playwright` job), a throwaway PR was opened, and a direct merge was attempted through the API: `mergeable_state` read `"blocked"` and the merge call was refused outright — `405 Repository rule violations found — Required status check "playwright" is in progress.` A required check **blocked a merge on a private repo**, which is the condition this section pre-committed to, met exactly as written and on **Pro** rather than Team. So the Rulesets UI copy quoted above is **wrong for rulesets on Pro**, not merely stale — and the community report that a Pro account was refused enforcement is not reproduced here. The discipline that produced this is the point and is unchanged: the condition was an observation, the observation was cheap, and it arrived before anyone bought anything on the strength of a message. **Consequences:** the ruleset steps under *Standing up CI on a repo* are **actionable today**, per repo, once that repo's CI check has run at least once and is therefore selectable as a required check; a leg no longer treats them as a no-op and no longer skips them on the grounds that the repo is private; and the enforced merge gate is no longer only the delivery loop's merge leg. **What remains open, and is the Owner's:** whether any Team-only capability still does not work on Pro, and therefore what A1-313's scope should now be — APP-1451 found that Team is not a coherent target for a personal account at all, so A1-313 may narrow or resolve rather than complete. Nothing here changes A1-313; it is named as the Owner's to re-scope. (APP-1438's comment thread carries the full probe — ruleset config, the PR, the exact API error. PR closed unmerged, probe only. APP-1673.)

The soft-gated arrangement below is **Option B, decided by the Owner (2026-07-28)**, and it held from then until the observation above. It is retained because two of its three parts survive the change unaltered — read it as the standing arrangement with the first bullet still live, the second amended by the observation, and the third and fourth still the rule on how this class of work is ticketed:

- CI still runs and is visible on every PR; the **enforced merge gate is the delivery loop's merge leg** — `skill-merge-pr` refuses to merge on red or missing CI, and that is what protects `main` in practice.
- **The on-upgrade checklist is the only place required-check work exists while soft-gated.** Enforcement is one org-wide switch, so it is owned by one ticket: **A1-313** (upgrade the org to Team, then enforce rulesets across the repos), standing on decision **A1-254** (a1.OS). When a repo's CI lands, **add that repo as a line on A1-313's checklist** and stop there. Do not file a per-repo `OPS: make the CI check required` leaf, and do not carry it as an unticked acceptance criterion on the build ticket. **"Do not attempt the ruleset step on a private repo" is retired by the observation above** — since 2026-09-23 the step works on Pro and a repo whose CI has run once is configured directly, as part of standing its CI up rather than as deferred work. **The checklist is still the work list and still the only artefact**: A1-313 already carries the line per repo, so walking that checklist is how the per-repo work happens, and the *one owner, not a leaf per repo* pattern below is unchanged — it was always about not multiplying one question into N parked tickets, and un-gating the capability removes the parking, not the pattern. What changes is only that the lines are now actionable instead of waiting.
- **This is structural, not advisory, and the difference is the point.** The first version of this note said "don't file a per-repo leaf" and did not hold — **APP-696** (bot-trader) was created *after* it landed, joining **A1-244** (operator-console); each such leaf then parks in Blocked or Backlog, re-surfaces on every triage and coordinate sweep, and re-prompts a conclusion the Owner already settled. Both were cancelled and folded into A1-313's checklist on 2026-08-10 (APP-764). The rule that works is not "prefer not to file" but "the checklist is the only artefact — the leaf does not exist."
- The per-repo required-check work resumes only once the upgrade lands, at which point A1-313's checklist is already the list of repos to walk. (APP-706, rediscovered live on A1-244 / operator-console, 2026-07-28; APP-764, 2026-08-10.)
**A required check is satisfied by the check run attached to the PR's own check suite — a `workflow_dispatch`-triggered run of the same job, green on the same head SHA, does not clear the gate.** Now that enforcement is live (above), this is the first observed way a PR whose required check reads green still refuses to merge. The shape: `get_check_runs` on the head SHA shows the required job `completed`/`success`, `get_status` shows no context of that name at all (it is a check run, not a legacy status), nothing has moved between the read and the call — and `mcp__github__merge_pull_request` with `expectedHeadSha` set is refused with `405 Repository rule violations found — Required status check "<job>" is expected.` Read the 405's wording: *"is expected"* means the ruleset cannot see a qualifying run, which is a different failure from *"is in progress"* (the probe above) and from *"is failing"*. **So the reading is not "the check is green, the API is wrong" — it is "the run that is green is the wrong run."** Do not retry the merge, do not push an empty commit to re-kick it, and never reach for an admin bypass: the merge is genuinely gated and the gate is correct about what it is looking at.

- **The cause is the trigger, so the remedy is at the trigger.** A run started by `workflow_dispatch` is not associated with the pull request the way a `pull_request`-triggered run is. Where a workflow re-triggers a required check after a bot commit — because a `GITHUB_TOKEN` push fires no `pull_request` event (*Standing up CI on a repo*) — **dispatching the job is the wrong re-trigger, and approving the run the bot commit already queued is the right one** (*A workflow run can sit `action_required`*, below). Dispatch is a fallback that produces a green check nobody can merge on.
- **Where a PR is already in this state it is the Owner's to clear**, by merging from the GitHub UI or by producing a `pull_request`-triggered run of the job. Route it once as a genuine merge failure and quote the 405 verbatim; this is not a bounded CI wait and polling it changes nothing.
- The repo-lane half — making each repo's snapshot-update workflow take the approve-via-API path rather than the dispatch fallback — is **APP-1718's rollout**, already ticketed; do not file it again. Confirm `workflow_dispatch` against `assoc-one/meirionpritchard-com` `origin/main:.github/workflows/update-snapshots.yml` before writing a per-repo claim; expected both an `update-snapshots` label trigger and a `workflow_dispatch` trigger, with the API-approval step ahead of the dispatch fallback.

(Worked case: `assoc-one/meirionpritchard-com` PR #175 / A1-412, 2026-09-24 — head `29a4302a66d0a909ab4444bc9a3eedaea3ed8edf`, `playwright` `completed`/`success` on that exact SHA and re-read unchanged after the refusal, produced by `update-snapshots.yml`'s `workflow_dispatch` fallback; the squash merge was refused `405 … Required status check "playwright" is expected.` The Owner merged by hand — no empty-commit kick, no bypass. This is also the **second independent observation** that a required check enforces on a private repo on Pro, the day after the 2026-09-23 probe, so the condition this section pre-committed to is not a one-off. APP-1725.)

### The general pattern — one owner, not a leaf per repo

Required checks are the first instance of a shape worth naming, because the estate will keep producing it: **a capability gated org-wide by a single deferred decision does not generate a ticket per repo.** Filing one per repo multiplies a single unanswered question into N parked leaves, each of which re-asks it — the answer never changes, but the asking is unbounded and lands on the Owner.

So when a capability is blocked by one org-level switch (a plan upgrade, an org policy, a shared credential, a paid tier):

- **One ticket owns the switch**, and it carries the checklist of everything that will be applied once the switch flips.
- **Per-repo work adds a line to that checklist**, never a ticket of its own.
- **The convention that spawns the work says so at the point of spawning**, so the sequence is not re-derived per repo. A note further down the file that the CI-setup steps do not reference is the failure mode APP-764 recorded.

### Pre-merge evidence for a brand-new workflow — there is no `workflow_dispatch` path

GitHub only lists and dispatches workflows that exist on the **default branch**. A workflow file present only on a PR branch is not registered yet, so `mcp__github__actions_run_trigger` (`run_workflow`) against it returns **404 Not Found**, and `mcp__github__actions_list` (`list_workflows`) does not show it. So a ticket whose acceptance criteria ask for "a run of this new job on this ticket's own PR, linked as evidence, before merge" has **no dispatch path** — `workflow_dispatch` cannot serve pre-merge evidence for a workflow that has never been on `main`. Choose one of two paths **when the ticket is authored**, not mid-run:

- **(a) Add `pull_request` as a trigger** so the job runs on the PR itself and produces the evidence run. Safe where the job cannot fail the PR unexpectedly (e.g. a script that always exits 0). Note in the ticket and PR body that `pull_request` is a trigger — temporarily or permanently — precisely because `workflow_dispatch` cannot serve the need pre-merge. This is a deviation from a schedule/on-demand-only preference and is called out as one.
- **(b) Reframe the AC to accept a post-merge run.** Once the workflow lands on `main` it is registered and dispatchable, so the evidence run is produced by a scheduled or dispatched run **after** merge and linked back to the ticket.

**A PR's own `opened` event does not always fire the run — after about 60 seconds of zero runs, force a `synchronize` rather than keep polling.** Where a fresh PR shows no workflow runs at all — `list_workflow_runs` empty filtered by workflow, filtered by branch and unfiltered alike — the available readings are that the workflow is misconfigured or that Actions is down, and both are wrong and expensive: one sends a run to rewrite a correct workflow file, the other to poll a PR that will never produce one. Push an empty commit to the head branch instead; the `synchronize` event starts the run. Editing the PR does not substitute — `edited` is not a default `pull_request` trigger type, so changing the base with `update_pull_request` produces nothing. Root cause is unconfirmed and this is one observation, so treat it as a recovery to try early rather than an explanation. (Worked case: `assoc-one/aledpritchard-com` PR #37, 2026-09-14 — a negative-control PR identical to PR #36 in repo, actor, workflow file, draft state and base, whose CI never started; roughly 8 polls and 5 minutes were spent before an empty commit produced a run — APP-1462.)

Either is fine; what is not fine is a pre-merge `workflow_dispatch` AC on a brand-new workflow, which cannot be met. (Worked case: A1-240, `assoc-one/firmup`, 2026-07-21 — the new job's `workflow_dispatch` 404'd because the file was only on the PR branch, and `pull_request` was added as the pre-merge evidence path — APP-632.) The AC-authoring side of this (how `skill-build-ticket` should frame a "ship a new CI job + link an evidence run" ticket) is the exec skill's concern; this note is the connector limitation the framing has to work around.

## CI coverage and the sandbox test environment

- **A repo's CI must gate *every* language and package it holds — "CI green" is worth only what CI runs.** A `ci.yml` that covers the TypeScript `app/*` packages but not the Python `research/*` ones leaves those packages with no merge gate, so a "CI present, concluded, green" DoD box reads identically whether CI exercises 100% or 40% of the tests behind the acceptance criteria. When standing up or extending CI, cover each language/package root in the repo; where an AC is evidenced only by a suite CI does not run, that box rests on whoever happened to run it locally, not on the gate. The QA-side companion — QA stating which ACs the merge gate covers versus which rest on a local run — is `skill-review-pr`'s. (Worked case: bot-trader's three `research/*` Python packages — ~295 tests across `fx-carry-study`, `fx-momentum-study`, `fx-cost-model` — sat outside `ci.yml`, so two of APP-751's six ACs were evidenced solely by pytest a reviewer happened to have a venv for — APP-753.)
- **The cloud sandbox ships a fixed Playwright browser build, and the build number moves with the image — name the path, never the number.** The image carries Chromium and its headless shell under `/opt/pw-browsers` with `PLAYWRIGHT_BROWSERS_PATH` pointed at that directory, and a repo pinning a newer `@playwright/test` wants a different build and fails with `Executable doesn't exist at …`, while `playwright install` is both discouraged and egress-blocked. This is an *environmental* failure, not a diff failure (see `skill-build-ticket`'s environmental-vs-real gate rule and its claim-time instrument check). **A pinned build number in canon, in a repo's `CLAUDE.md` or in a script's default goes stale silently and costs a dead turn at the first launch after the image moves** — the error names a missing executable, which reads as a broken repo rather than a moved image. So the browser is described by how it resolves, not by which build it is: let the global Playwright resolve its own default from `PLAYWRIGHT_BROWSERS_PATH`, or read the directory and use the version-independent `/opt/pw-browsers/chromium` symlink, and where a script must hold an explicit path, fall back to `chromium.executablePath()` when the pinned one is absent rather than failing on it. The clean per-repo fix for a repo that does pin is to make its `PLAYWRIGHT_EXECUTABLE_PATH` hook set `use.launchOptions.executablePath` — not `use.executablePath`, which is silently ignored — so a run can point at whatever build is installed; that is a repo-lane change, filed per repo. **Verified on the refine surface, 2026-10-27:** `/opt/pw-browsers` holds `chromium-1243`, `chromium_headless_shell-1243` and `ffmpeg-1011` and no 1194 of any kind, the binary sits at `chrome-linux64/chrome` rather than the `chrome-linux/chrome` an older build used, `PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers`, and `/opt/pw-browsers/chromium` resolves to the 1243 binary. Build numbers and sub-path shapes are properties of the image and are read, never assumed — `convention-host-access`, *Measuring a live page from the sandbox*. (Worked cases: meirionpritchard-com's `playwright.config.ts` set the wrong key, so its env-var hook silently no-op'd — APP-713. Then the image moved 1194 → 1243 and the pinned path failed on the A1-803 QA leg and the A1-798 exec leg on the same day, each costing a turn to discover the real directory by hand, with the firmup-operator, Luna, mbn-theme and meirionpritchard-com `CLAUDE.md` files and their verify and guard scripts all still naming 1194 — those repo-side strings are the filing legs' **report** and are unverified here, no repo ref being readable from the authoring surface, while the image facts above were re-measured — APP-2661.)

- **`document.fonts.check()` returns `true` unconditionally in the sandbox's pinned Chromium build — iterate `document.fonts` and read each `FontFace.status` instead.** In the image's pinned build (`/opt/pw-browsers/chromium-1194` — **verified present on the refine surface, 2026-09-25**, alongside `chromium_headless_shell-1194`) `.check()` was measured returning `true` for a completely unregistered family (`"400 16px totally-bogus-family-xyz-123"`) matching no `@font-face` and no local or system font, with the real family's stylesheet request aborted — so a font-loading assertion built on `.check()` passes whether or not the font actually loaded. This is the same instrument class as `get_workflow_run_usage`'s zero billable minutes and the `runner_id: 0` case (*Reading the GitHub MCP safely*): a reading that looks meaningful and is not. The working alternative is to iterate the `FontFaceSet` and read each face's own `.status`, which correctly separated `loaded` from `unloaded` — and a face whose request was aborted did not appear in `document.fonts` at all, which is itself the signal. So **any sandbox-run font assertion iterates `document.fonts`, and `.check()` is exercised only in a CI-only test**, where it behaves: the same assertion passed correctly in CI, which is what makes this the pinned build rather than Chromium or Playwright generally. Unverified — the `.check()`-returns-true observation and the `FontFace.status` alternative are the A1-412 session's report and were not re-run here, because no browser was driven on the refine surface; that flag covers those two premises only, not the build path, which was verified. (Worked case: `assoc-one/meirionpritchard-com` PR #175 / A1-412, 2026-09-24 — `tests/font-kit.spec.ts`'s `familyLoaded()` helper is built on the iteration while a CI-only test still exercises `.check()` to meet the ticket's literal criterion. Confirm `familyLoaded` against `origin/main:tests/font-kit.spec.ts` before writing a per-repo claim; expected the helper plus a file-banner comment naming this failure mode. APP-1731.)
- **A redirected or backgrounded Playwright run uses `--reporter=line`, or writes JSON to a file — never `list`; and a log's growth is never the run's outcome.** The durable rule is the second clause, and it holds whatever the reporter does with buffering: a run whose output is not a terminal uses `--reporter=line`, or `--reporter=list,json` with the JSON written to a file (`PLAYWRIGHT_JSON_OUTPUT_NAME`, or the config's `outputFile`), and its outcome is read from the runner's own summary line once it exits (`skill-build-ticket`) — never inferred from how far a log has grown, and never from `| head`, which loses the result outright. **The buffering behaviour itself is surface-specific and must be restated with its surface, never promoted to a mechanism.** Redirected, `npx playwright test --reporter=list > run.log` was observed leaving a zero-byte log until the run exited, and the late buffered flushes read like live progress; the conditions of that observation are unknown — possibly a backgrounded-capture path, possibly a different Playwright version — and it has not been reproduced since (APP-1346). Measured against it on the current delivery image, `--reporter=list` backgrounded three ways — redirected with `2>&1`, stdout-only, and piped through `cat` — wrote per-test lines progressively in all three, sampled every 5 seconds and growing steadily from roughly t=15–20s until exit; confirm `@playwright/test` version against `origin/main:package.json` before restating that reading for a repo, expected `1.61.0` on Node 22 (APP-1798). So a leg that meets a silent log recognises it, and a leg that watches a log grow still learns nothing about the result. A repo's `CLAUDE.md` restating any of this for its own suite is repo-lane — and restates the surface with it: writing a surface-specific reading into a doc as an unconditional property, "measured here", without re-measuring is how this claim spread in the first place (APP-1584). (Worked case: a leg believed about 145 results after roughly an hour; the real run was 474 passed and 12 failed of 486 in 12m35s, and one full run was wasted — APP-1346.)

- **A repo's own documented healthy-run invariant is expressed as the base-vs-head diff of failing spec names, never as an absolute pass/fail count and never as a fixed list of spec files.** An egress block widens the red set, so an invariant written as a count — "183 passed / 4 failed, every red confined to these two spec files" — is narrower than what a blocked sandbox run actually produces, and a correct run then reads as a failure. The substance is already canon on both legs that read it: `skill-build-ticket` step 4 requires the stash-and-rerun base-versus-head comparison and reports that comparison rather than the bare figure, and `skill-review-pr` forbids quoting a copied absolute figure. What neither says is that the repo's **own** `CLAUDE.md` can be the stale source — which is where a leg looks first, and which is why the invariant's *shape* belongs here. The repo doc restating its suite's healthy run is repo-lane; the shape it must take is stated here. (Worked case: `meirionpritchard-com` PR #161 / A1-462 QA re-review, 2026-09-22 — the documented 183/4 could not be reproduced; an isolated worktree gave 55 passed / 132 failed *identically* on the PR head and on unmodified `main`, the failing sets byte-for-byte identical between the two, with CI's own Playwright job green at that head SHA. The property the invariant exists to check — no *new* red spec — was verifiable; the documented count was not. APP-1654.)

### Screenshot baselines are CI-rendered, never sandbox-rendered

**Owner decision, 2026-09-24: a visual-regression baseline (`toHaveScreenshot` and the like) is produced in CI and committed back by a workflow. A delivery sandbox never writes one.** This is not a preference about tidiness — the sandbox renders a different page from CI and a builder cannot close the gap: egress-blocked content (Sanity) and egress-blocked fonts (`use.typekit.net`) are simply absent, and the framework's own dev-tools overlay renders text ("N Issues") that CI does not have. A baseline committed from the sandbox bakes those differences in, and every later CI run then fails against it. The sandbox also cannot read CI's own verdict directly: the `playwright-report` artifact download redirects to `productionresultssa*.blob.core.windows.net`, outside the egress policy, so *"fetch the report and compare"* is not available either. On 2026-09-23 that combination stalled a visual PR for hours.

The pattern, in the order it has to hold (reference implementation: `meirionpritchard-com/.github/workflows/update-snapshots.yml`):

1. **Hide the framework dev overlay in the screenshot config, not by turning the overlay off.** `expect.toHaveScreenshot.stylePath` pointing at a stylesheet that hides the overlay element is what works; `devIndicators: false` is **not** enough. Confirm `stylePath` against the repo's `origin/main:playwright.config.ts` before writing a per-repo claim; expected `expect.toHaveScreenshot.stylePath` set to a CSS file whose rule hides the `nextjs-portal` element.
2. **The update is a workflow, triggered two ways.** An `update-snapshots` **PR label** and `workflow_dispatch` (branch plus a grep). It runs the suite with `--update-snapshots=changed`, commits **only** the snapshot directory as `github-actions[bot]`, refuses `main`, and ignores fork PRs. The label trigger is what lets the workflow's own PR exercise it, because a brand-new workflow is not dispatchable until it is on the default branch (*Pre-merge evidence for a brand-new workflow*).

   **And it builds the PR branch head, not the merge ref the required check uses — so a branch behind `main` regenerates nothing and still concludes success.** The required screenshot check runs against the merge ref, which carries `main`'s baselines as well as the branch's; the update workflow runs the suite against the branch head alone. Where the failing baselines exist only on `main` — added by a pull request that merged while this one was open — the branch holds no spec to re-capture, `--update-snapshots=changed` changes nothing, no commit is made, and the run still ends `success`. That reading is indistinguishable from "the baselines were already correct", which is the quiet failure: the label has been spent, the workflow is green, and the pull request's red check is untouched. So where an update run concludes with **no commit** while the required check at that head is red, establish first whether the base has moved — merge `origin/main` into the branch and dispatch the update again — rather than reading the green run as evidence about the baselines. This is the same base-moved-under-the-branch family as *A `pull_request` run tests the merge with `main`; a `workflow_dispatch` run tests the branch head*, which states the general form of two refs not being comparable evidence; here the two refs are the required check's and the generator's, and a branch-behind check costs one command against a lost round per pull request. (Worked case: `assoc-one/meirionpritchard-com`, 2026-10-21 — `update-snapshots.yml` did nothing on PR #267 and PR #257, ending `success` with no commit both times; the failing `b-text` and `b-captions` baselines existed only on `main`, added by PR #266, and each pull request lost one round until `main` was merged into the branch and the workflow re-dispatched. Reported by the operator-a1 driver session and **unverified** here, each clause covering only itself: which ref the workflow checks out, its exit path when zero snapshots change, the required check's use of the merge ref, the pull request numbers and their merge order, and the baseline names. No repo or GitHub surface is readable from the authoring surface — APP-2582.)

3. **The bot commit's `pull_request` runs land `action_required`, and the workflow approves them through the API with its own `GITHUB_TOKEN`** (proven 2026-09-23). Dispatching the required check is the **fallback only**, and a poor one: a dispatched run reads green and still does not satisfy the required check (*Required checks are enforceable per repo on Pro*; *A workflow run can sit `action_required`*).
4. **A person reads the committed PNG diff in the PR.** The workflow updates the baseline; it does not adjudicate it. A `toHaveScreenshot` red on an intended change is an operator review gate and is routed once, not re-checked on a timer (*A CI red only a person can adjudicate*).

**A fixture page that stacks element screenshots couples its sections: adding, removing or reordering one shifts the baselines of every section after it.** An element screenshot's dimensions are the rendered element's own, rounded — so a section that merely **moves** can re-round by a pixel and go red against a baseline nothing about that section changed. The red lands on sections the diff never touched, is one pixel, holds identically across retries and appears in every Playwright project at once — which is the signature of a real regression rather than of a flake, so it reads as one and gets diagnosed as one. **So a change that adds, removes or reorders a section on a fixture page expects the update-snapshots step up front**: budget it into the ticket rather than paying a full CI cycle to discover it, and read a red on an untouched neighbour of an edited section as this coupling before reading it as a regression in that neighbour. The confirming evidence is cheap and is stated rather than assumed — name which tests moved, and whether the moved ones sit **after** the edit in document order while the ones before it stayed green. A sandbox run cannot stand in for the check, for the reasons above: the baseline it would compare against is not the one CI renders.

(Worked case: `assoc-one/meirionpritchard-com`, 2026-10-05 — deleting one section from the fixtures page, along with that section's own screenshot test and nothing else, turned two unrelated caption tests red in all three Playwright projects, each one pixel shorter than baseline, identically across retries, while two other sections did not move; it cost one full CI cycle of roughly 12 minutes plus a diagnosis before an update-snapshots run committed the six expected PNGs. Unverified — no repo access from this refine surface: the fixtures page's path, the section and test names, the pixel figures and the commit identifier are reported from that note and not observed, and the re-rounding cause is **inferred** from which tests moved rather than measured against the rendered offsets. The rule above is written so that a leg confirms the ordering itself rather than inheriting the inference. The repo's own baseline runbook does not carry this line, which is a repo-lane ticket. APP-2062.)

The Storybook-side statement of the same rule — that the sandbox is not an arbiter for a screenshot — is `convention-storybook`'s *Visual regression* row, which points here rather than restating the mechanism, so the two cannot drift. The per-repo rollout of this workflow and the a1.OS playbook update are **APP-1718** and its siblings, already ticketed as delivery work; do not file them again. (Worked case: `assoc-one/meirionpritchard-com` — A1-507 / PR #174 built it, A1-516 / PR #179 added the API-approval step, first real use on PR #172. APP-1717.)

## Chromatic — the "UI Tests" pending-baseline status is an operator review gate, not a CI wait and not a blocker

> **DEFERRED by Owner decision, 2026-08-13 (APP-854) — the "UI Tests" pending-baseline status is no longer a merge gate.** The merge leg **merges on the GitHub Actions check runs alone** and does **not** route a PR to In Review on a pending `"UI Tests"` commit status. Reasons: assoc-one hit the Chromatic free-plan monthly snapshot cap (UI Tests + UI Review paused; Storybook publishing continues), and the per-PR baseline-acceptance step was being waved through blind — a review layer that added no trust. **What is unaffected:** the client-facing **Storybook publish + in-place commenting** (kept), and the future **Figma design-comparison / UI Review** role (never a merge gate; not live). **To reinstate** later, either re-add the `"UI Tests"` routing described below to the merge leg, or keep the gate but fit the free snapshot budget via the APP-621 lever (TurboSnap + Work-section-only + Chromium-only) rather than paying. The routing detail below is retained **only** as that reinstate reference; it does not describe current behaviour. The check-run-vs-commit-status *reading* discipline (read both) still stands on its own merits — only the route-to-In-Review-on-pending-`UI Tests` behaviour is retired.

On a repo wired to Chromatic (`assoc-one/meirionpritchard-com` today), a PR can carry every GitHub Action check green and still sit at `mergeable_state: unstable` because Chromatic's own commit status — **"UI Tests"** — is *pending*: *"N visual and accessibility changes must be accepted as baselines."*

**This status never concludes on its own.** It waits on a person opening the Chromatic UI and accepting or rejecting the visual diff. So `skill-merge-pr`'s bounded CI-wait does not apply — polling it burns the whole window and ends where it started. Recognise it on sight by the shape: GitHub checks green, `chromatic` *action* green, `UI Tests` *app status* pending — and note that the last of the three is a **commit status**, invisible to a check-run read (see *Reading CI / PR state in autonomous runs*).

- **Do not wait, and do not merge.**
- **Route the ticket to In Review, label `human`, assigned to Aled**, escalating by age to Urgent if it lingers. Name the specific baselines to accept and include the Chromatic build link, so the ask is actionable without opening the PR. **This is not Blocked** — see the reasoning below.

- **The Chromatic build URL is read from the `chromatic` job's log, not from the check run's `details_url`.** The `chromatic` check's `details_url` points at the GitHub Actions log, not at Chromatic, and the build URL is not posted as a PR comment by default — it is printed inside that job's log output. So a leg naming the build link pulls it out of the job log content (`get_job_logs`, by the tail ladder in *Reading the GitHub MCP safely*), never off the check run's fields and never from a PR comment it assumes is there. The same URL is what a story-specific review link is built on (`convention-storybook`, *Review links deep-link to the story under review*). (Worked case: a live review session, 2026-09-22 — the `details_url` route gave the Actions log and the real Chromatic URL had to be read out of the job log live. APP-1653.)
- **It fires on visual-adjacent changes that are not component changes** — a docs page, a new story, a `Tokens.mdx` update. Two tickets hit it in one run (A1-116, A1-234, 2026-07-21).
- **Open, for the operator:** whether a narrower Chromatic scope (TurboSnap) would stop unrelated docs and story changes tripping a baseline review, and whether baseline acceptance can be batched at his existing approval touchpoint rather than a per-PR round-trip. Both are decisions, not agent actions. (APP-621.)

### Why In Review and not Blocked — the test, applied

This entry previously said *"Route the ticket to Blocked + `human`"* (APP-621, 2026-07-21). That routing was wrong, and it stood against `skill-review-pr` and `convention-linear`, which both say In Review — leaving each run to adjudicate a canon conflict at the moment it least wants to (worked case: A1-299 / `meirionpritchard-com` PR #87, 2026-07-31 — APP-734). It is corrected here.

The deciding argument is not that two artefacts said one thing and one said another. It is `convention-linear`'s unverifiable-DoD test: **"would separate work make it verifiable?"** Apply it literally:

- **The instrument is present and working.** Chromatic is installed, the action ran, and the diff has been computed and is sitting in the UI waiting to be looked at. Nothing is missing, unreachable or unset. There is no separate piece of work that would make this box tickable — no ticket to file, no runner to stand up, no credential to add.
- **Only Aled's judgement clears it.** Accepting a baseline is a person looking at a visual diff and deciding whether it is the intended change. That is precisely the "an 'it looks right' judgement, a call no instrument can make" case, which the test routes to **In Review**, `human`, assigned, escalating by age.
- **Blocked would name no dependency.** `convention-linear` requires a Blocked ticket to carry a blocked-by relation to the ticket that installs the missing instrument. Here there is no such ticket and never could be, so the item would read as dependency-bound while naming no dependency — the exact failure mode that rule was written to stop, and it would sit outside the "In Review = awaiting your sign-off" view where the operator actually looks.

`skill-review-pr`'s interactive-surface rule lands in the same place — driving a live surface and judging what it shows is operator-review sub-case (b), In Review + `human`, never Blocked — but it agrees because it applies the same test, not because it is a second vote. A Chromatic baseline review is an interactive-surface judgement in a vendor UI; it is the A1-129 pattern with a different window.

**What survives from the old entry unchanged:** the recognition signal, "do not wait, do not merge", naming the specific baselines and the build link, and the open operator questions. Only the state changes.

One distinction worth holding, because it is the strongest argument for the old reading: the pending status does genuinely make the PR unmergeable, so it *feels* like a blocker. But Blocked is about **who or what must act next**, not about whether the merge button is currently live. The next action is the operator's eyes and nothing else, so the ticket belongs where his sign-off queue is.

## A CI red only a person can adjudicate is an operator review gate — route it once, to the person, and never re-check it on a timer

The Chromatic entry above describes one instrument, and its routing is deferred. **The test underneath it is live, general and applies to any CI failure whose root cause is a difference only a person can judge as intended or not** — a Playwright `toHaveScreenshot` snapshot diff, Chromatic's pending baseline, a visual-regression tool's unaccepted change, any assertion whose red means *this looks different* rather than *this is broken*. Apply `convention-linear`'s unverifiable-DoD test, exactly as *Why In Review and not Blocked* applies it: the instrument is present and working, the diff has been computed and is sitting there waiting to be looked at, **no separate work would make the box tickable**, and only the Owner's judgement clears it. That is the "an 'it looks right' judgement, a call no instrument can make" case, so the routing is the same whatever produced the red: **In Review, label `human`, assigned to Aled, escalating by age** — not Blocked, which would name a dependency that does not exist.

**And the behavioural half, which is where this goes wrong in practice: a human-eyeball gate is never served by a silent re-check.** The default posture for an ordinary CI red — report once on the PR, then re-check quietly while the blocker holds — is correct for a blocker that will conclude on its own. A human-eyeball gate **never concludes on its own**, so a silent timer re-check is not patience, it is an unbounded wait nobody has been told about: the PR comment is written, the re-checks are invisible, and the only person who can clear it does not know they are the blocker. So on recognising this class:

- **Send one direct, concise message to the person who owns the review** — not only a PR comment — naming exactly what to look at, why the diff is expected or not, and the link that opens it. For a Chromatic baseline that link is read out of the `chromatic` job's log, never off the check run's `details_url` (above). For a Playwright snapshot failure it is the report or the diff artefact the run produced.
- **Stop the timer.** No further re-checks until they respond. Escalate by **age** on the ticket, per `convention-linear`'s ladder, which is how a waiting item climbs without collecting repeat comments.
- **Do not wait and do not merge**, unchanged from the Chromatic entry.

**The recognition signal is the failure's cause, not its name.** A `toHaveScreenshot` red on a change that intentionally alters what a page looks like is this class; the same assertion red because a page did not render is an ordinary defect. Read the diff before choosing, and where it is genuinely ambiguous, route it — the cost of routing an ordinary red is one message, and the cost of silently re-checking a human gate is measured in the Owner's hours. This rule lives in canon and **not** in any repo's `CLAUDE.md`: a local copy of PR-behaviour rules is what drifted before (APP-806). (Worked case: `assoc-one/meirionpritchard-com` PR #164, 2026-09-23 — the `playwright` check red on a `toHaveScreenshot` diff that was real, intentional and correct, which only a person could confirm. The generic CI-red posture was applied instead, a check-in was re-armed silently roughly **seven times over several hours**, and the wait ended only when the Owner asked whether anything was waiting on him. The Chromatic section had the right routing and could not be recognised as applying, because it is written around Chromatic's `"UI Tests"` commit status — APP-1670.)

## A workflow run can sit `action_required` — a run that never starts, on a same-repo PR

Distinct from everything above, and the quietest of the family: GitHub Actions can hold a workflow **run** at `action_required` — *"N workflows awaiting approval — Workflows will not run until approved by a user with write permissions"* — so the job never starts, and the required check reads *"Expected — Waiting for status to be reported"* indefinitely. **This is not a slow run and it is not a red check; it is a permission gate in front of the run.** It has been observed on a **same-repo, non-fork** PR authored by the repo's own delivery identity, which is the case the documented outside-collaborator rules do not obviously cover.

Recognise it by the pair: a required check sitting in `Expected` with no run behind it, and one or more runs whose conclusion is `action_required` (`list_workflow_runs` / `list_workflow_jobs`, by the ladder in *Reading the GitHub MCP safely*). An **empty** run list is the other thing entirely — a PR whose `opened` event did not fire, fixed by forcing a `synchronize` (*Pre-merge evidence for a brand-new workflow*). **Check for an `action_required` run before pushing an empty commit**, or the empty commit queues a second run into the same gate and the PR reads busier while being no closer.

There are two ways past it, and which applies depends on whether a workflow can act on your behalf:

- **A workflow that produced the commit can approve its own follow-on runs through the API with `GITHUB_TOKEN`** — proven on `meirionpritchard-com`'s `update-snapshots.yml`, 2026-09-23, where the bot's snapshot commit queued `pull_request` runs at `action_required` and the workflow approved them itself (*Screenshot baselines are CI-rendered, never sandbox-rendered*). That is the path to build into any workflow that commits to a PR branch. It is also why dispatching the check instead is wrong: a dispatched run is green and still does not satisfy the required check (*Required checks are enforceable per repo on Pro*).
- **Otherwise it is the Owner's click and nothing else.** A session has no path to "Approve workflows to run". Unverified — whether any `mcp__github__*` tool approves a pending workflow run was not reached for on the live run, and the GitHub MCP is not mounted on the refine surface, so its absence could not be enumerated here; that flag covers the tool-absence premise only. So this is an operator gate by the test in *A CI red only a person can adjudicate*: send one direct message naming the PR and what to click, stop the timer, escalate by age — and **never poll it**, because the run that would conclude the poll has not started and will not.

**Named, not filed — the settings lever is the Owner's.** Repo → Settings → Actions → General → *Approve workflow runs* decides whether this recurs at all, and whether the delivery identity is being treated as an outside or first-time contributor. That is a repository-configuration change only the Owner can make, so it is named here and carried on the note: it is not a ticket, not a checklist line, and not an agent action. Until it is settled the recognition above is the whole remedy, and the recognition is worth having either way — a gate that is switched off is still a gate a future run may meet on another repo.

(Worked case: `assoc-one/meirionpritchard-com` PR #175 / A1-412, 2026-09-24 — the Owner opened the PR and saw *"3 workflows awaiting approval"* alongside `playwright` reading *"Expected — Waiting for status to be reported"*; his click was the only way through, and was followed by the separate required-check refusal above. Same-repo PR, not a fork, authored by the delivery identity. APP-1732.)

## A `pull_request` run tests the merge with `main`; a `workflow_dispatch` run tests the branch head — so the two are never comparable evidence

GitHub builds a `pull_request` run against the **merge ref** — the PR's head merged with the base — and a `workflow_dispatch` run against the **branch head** alone. Two runs of the same job on the same head SHA therefore exercise two different trees, and the difference is invisible in every surface a leg reads: same SHA, same job name, same check list. Two consequences, and both have cost a run:

- **A CI-only failure that never reproduces locally is a moved base before it is anything else.** Where `main` has advanced since the branch point, the merge ref contains code the branch has never been built against, and a **semantic** conflict — a removed constant, a renamed export, a changed signature — produces no textual conflict and no merge marker. The failure is then 100% deterministic in CI and 100% absent locally, which is the signature of an environment problem and reads as flake, a bundler fault or a timing race. So the **first** step on any CI red that will not reproduce is to establish whether the base moved — `git log $(git merge-base HEAD origin/main)..origin/main` — and, where it has, merge `origin/main` into the branch and reproduce against the merged tree before theorising about the environment at all. This sits ahead of both legs of `skill-build-ticket`'s local comparison, which control for the shell and for the branch and neither of which can see the base. Read a `typeof X === "undefined"` or a `ReferenceError` on an ordinary top-level identifier as the direct signal it is — the identifier is not in the tree that was tested — never as a bundler defect.
- **A green dispatch run is not evidence about the code, and a silent `pull_request` trigger is sometimes a signal rather than a platform fault.** GitHub does not run `pull_request` workflows while a PR has a merge conflict, because it cannot build the merge ref — so zero runs on a fresh push, with `mergeable_state` reading `dirty`, is the gate working. Read `mergeable_state`, or `git merge-tree --write-tree origin/main <head>`, before reaching for a dispatch: where the PR is dirty the remedy is to merge or rebase, not to dispatch. Dispatching instead returns a green check at the head, attached where the PR's own check normally sits, for a PR that cannot merge and whose code has never been built against `main` — the false-green mirror of the false red above, and a second reason the dispatch fallback does not satisfy a required check (*Required checks are enforceable per repo on Pro*). Where a dispatch has already been fired and the automatic run then lands as well, read `get_check_runs` and cancel the duplicate (`actions_run_trigger`, `cancel_workflow_run`): the reason is runner minutes, not a false signal — the two runs disagree because they tested different trees, and the `pull_request` one is the one that counts.

The 60-second empty-run recovery (*Pre-merge evidence for a brand-new workflow*) applies to a PR with a clean merge state and no runs; it is not the remedy for a dirty one, where forcing a `synchronize` produces nothing because the merge ref is still unbuildable.

(Worked case: `assoc-one/meirionpritchard-com` PR #206 / A1-554, 2026-09-29 to 2026-09-30 — a regression-guard spec red in CI and green locally, chased across roughly eight CI rounds of 20–75 minutes each as dev-server timing instability, an unexplained Turbopack `ReferenceError`, runner contention, and a font-load race with a fix pushed and then reverted, and written up as a full hand-off to a stronger model. `main` had merged A1-563, which removed the `ACTIVE_LINE_OFFSET` constant the branch referenced, with no textual conflict; the one "clean pass" was a `workflow_dispatch` run, which is what made a deterministic failure look intermittent. Merging `main` and adapting was green first time — `d61323a`. The duration theory the same incident produced is corrected under *A CI run's duration is not a diagnosis*. Second observation, PR #213 / A1-585, 2026-09-30: no `pull_request` run on head `8301f28` while the PR sat `dirty` after `main` moved, and `chromatic` and `typegen-check` had no dispatch path at all. Every repo, run and SHA fact here is reported from those runs and not observed — no repo is readable from the refine surface — no repo is readable from the refine surface; that flag covers the merge-ref semantics, the conflict-blocks-`pull_request` behaviour, the removed constant and all run identifiers. APP-1901, APP-1896.)

## A ticketless fix has a path — file the ticket first, or use the ticketless branch and PR form and link it afterwards

**A fix with no Linear ticket behind it has exactly two sanctioned paths, and a session reaching that point improvises a third only because neither is written down.** The rules above close every door at once: branch naming requires `claude/<ticket-id>`, the PR title requires `{TICKET-ID}: {short description}`, and `convention-linear`'s review-link rule requires a ticket to hang the link on — so a fix raised outside the board, typically from an Owner phone review where filing the ticket is the expensive part of the work, satisfies none of the three and has no shape to be written in. The two paths are these. **File the ticket first** and proceed through the ordinary `claude/<ticket-id>` convention: this is the default, and it is correct whenever the fix is larger than a line or will need a QA leg. Or, where the fix must land before a ticket exists, use the **ticketless form** — branch `claude/fix-<short-slug>`, PR title `fix: {short description}`, the raising context named in the first line of the PR body, and the Linear ticket filed and linked to that pull request **afterwards**, so the review-link rule is satisfied late rather than skipped. The failure this names is a ticketless pull request that is never back-linked, not the ticketless branch itself; the back-link is the obligation, and the branch form merely makes it possible to honour. (Worked case: a fix raised from an Owner phone review with no ticket ID available, where the branch name, the PR title and the review-link rule each demanded one and no sanctioned shape existed for any of the three. The review's circumstances and the absence of a ticket are **reported** from the filing note and were not re-observed here, no session transcript or repo being readable from the authoring surface. `APP-2831`.)

## Gotchas

- MCP tool parameter names differ from REST API names — always load schemas via ToolSearch, never assume.
- On a fresh clone, run `npm install` before the first npm script of *any* kind — a pre-install `format`/`lint` can succeed silently against the wrong toolchain and produce a false diff (see *Fresh clones*).
- On a fresh clone, run any content or codegen step the repo's `CLAUDE.md` or `package.json` names before the first type-check or test — a `Cannot find module` on a gitignored generated path is environmental, not a defect in the PR under review; build it and re-run before reporting (APP-1598; see *Fresh clones*).
- The harness's generic single-designated-branch instruction does not govern delivery-loop runs — `skill-build-ticket`'s `claude/<ticket-id>` per ticket does (see *Branch naming*).
- Never poll GitHub via raw `curl`/API token in an autonomous run — the egress proxy 403s it silently and a `-s` poll misreads the empty body as "checks passed" (see *Reading CI / PR state in autonomous runs*). Use `mcp__github__*` for all PR/CI reads.
- The session tool surface is **`gh` absent on some surfaces and present-but-token-limited on others, a set `GITHUB_TOKEN` possibly a placeholder (measured: `proxy-injected`), GitHub MCP for PR/CI state, HTTPS-only egress** — tested by whether an authenticated read returns data, never by whether the binary or the variable exists (*GitHub MCP tools*) — the documented `gh pr checks`/`gh api` watch patterns do not fail for one reason — `gh pr checks` returns nothing useful whatever the credential does, because GraphQL is refused outright (APP-935, APP-1353, APP-1461), while `gh api repos/{owner}/{repo}/...` can return data on an **attached** repo even where `gh auth status` reports the token invalid, and a 403 naming `add_repo` is an attachment fact rather than an auth failure (measured on the Pulse cloud surface 2026-10-23), and on Actions run-listing endpoints page with explicit `page=N` because `--paginate` follows a `Link` header onto a proxy-blocked numeric-ID path, though it stays fine for job listings (APP-1482; see *Reading CI / PR state*).
- A CI-poll loop's failure branch must **emit** (`… || { echo "POLL FAILED: $?"; sleep N; }`), never `continue` silently — a blind monitor reads identically to a running one, the same family as the APP-450 silent-`curl -s` false-green (APP-935; see *Reading CI / PR state*).
- For **liveness** (has a job concluded?) poll `list_workflow_jobs` on the run id — `get_check_runs` and `get_workflow_job` are cached and serve a stale `in_progress` for 20+ minutes, and cross-checking one against the other learns nothing; use `get_check_runs` only to enumerate checks and read commit-status gates, `get_job_logs` only to read a failure, and never `get_status` as liveness on an Actions repo (APP-938). **No status surface is trusted fresh**, `list_workflow_jobs` included — bound the wait by `run_started_at` arithmetic against the workflow's known median, treat two identical consecutive reads as possibly cached, and never cancel or re-dispatch on a stale read (APP-1509; see *Reading CI / PR state*).
- An elapsed-time claim about a CI job states `started_at` and the current time and the subtraction — never an impression from polling (APP-1018; see *Reading CI / PR state*).
- A CI run's **duration carries no cause** — establish the cause from the failing leg's own log, the first failure's timestamp against the step's start, never from the run's length or from a remembered band; and a genuinely variable suite gets a stated median band plus a per-leg `timeout-minutes`, never an absolute ceiling, with the measured figures in that repo's own `CLAUDE.md` (APP-1898; see *A CI run's duration is not a diagnosis*).
- In an unattended run `mcp__github__push_files` is the default for **new files and whole-file replacements** — a local write to a sensitive path (e.g. `SKILL.md`) raises an interactive approval gate that hangs the run. An **edit to an existing file** goes the other way, because `push_files` would mean re-emitting every unchanged line by hand: take the local `Edit` + `git commit` path where a local write has already landed ungated this session, otherwise read the content back from disk before passing it, and name the path in the PR body either way (APP-1287; see *Writing files in autonomous / cloud runs*).
- A publish ticket that touches a `SKILL.md` without regenerating the `public/` mirror fails the repo's build-manifest CI gate — **run `npm install && npm run build:manifest` and commit what it regenerates** rather than hand-constructing the mirror; the script does run in the cloud environment, and hand-construction carries the `.claude/tasks/` doubled-prefix and description→summary traps (see *Publish tickets targeting claude-ops*).
- Reading the GitHub MCP: default `minimal_output: true` on `actions_list` with a small `perPage` or it overflows the tool limit on a boilerplate-heavy run object, and note `actions_get`/`list_workflow_jobs` take `resource_id`, not `run_id` (see *Reading the GitHub MCP safely*).
- A `search/issues` query takes **one scoping qualifier** — `org:` and `repo:` in the same `q` OR together, so a per-repo count comes back as the org-wide total with no error raised. Read a per-repo figure from `repo:` alone, isolate the remainder with `-repo:`, and cross-check any count before it is published against a second query whose parts sum to the whole; `orgs/{org}/repos` is 403 on a session-bound surface, so per-repo search counts are the only enumeration route (`APP-3042`; see *Reading the GitHub MCP safely*).
- When a run must commit from a local clone (for a rebase `push_files` cannot do), a placeholder git author breaks Vercel's status check — `mergeable_state` sticks at `unstable` despite green CI. Set the author to `Claude <noreply@anthropic.com>` before committing (see *Local git operations*).
- Rebasing a shallow (`--depth 1`) clone produces spurious `add/add` conflicts across unrelated files — run `git fetch --unshallow` and confirm `git merge-base` succeeds before any rebase (see *Local git operations*).
- A fixture origin built with `git init --bare` needs `-b main`: `init.defaultBranch` is unset in the sandbox, so the bare repo's HEAD defaults to `master`, a clone of it checks nothing out, and that reads as a push that never landed — while `git fetch origin main`, the thing under test, works fine. The `fatal: expected 'acknowledgments', received 'packfile'` printed alongside it is `push.negotiate=true` over the local transport and is **cosmetic**: the push exits 0 (APP-2012; see *Building a fixture repo for a script that fetches from `origin`*).
- Adding a CI workflow file does not make the check required — that is a repo-admin ruleset step no agent can do (see *Standing up CI on a repo*). The branch-protection UI path is stale; rulesets is the live one. **Rulesets do enforce on a private repo on Pro** — observed blocking a real merge on 2026-09-23 and again on 2026-09-24 — so the ruleset step is actionable per repo once that repo's CI check has run at least once, and the Rulesets UI's "not until GitHub Team" copy is wrong rather than merely stale (APP-1673, APP-1725; see *Required checks are enforceable per repo on Pro*). **But a green check is not automatically a satisfied check:** a `workflow_dispatch`-triggered run of the required job does not clear the gate, and the 405 then says *"is expected"* rather than *"is failing"* (same section).
- **Per-repo required-check work is a line on A1-313's checklist, never a ticket of its own** — a filed leaf cannot be actioned, parks, and re-surfaces on every sweep re-asking a settled question (A1-244, APP-696; see *Required checks are enforceable per repo on Pro*). Since 2026-09-23 those lines are **actionable** rather than parked, which removes the waiting, not the pattern: a capability gated org-wide by one deferred decision still gets one owning ticket with a checklist, never a ticket per repo. A1-313's own scope is the Owner's to re-scope, since Team is not a coherent target for a personal account (APP-1451).
- A green check-run read is **not** evidence a third-party gate has cleared — Actions jobs are check runs (`get_check_runs`), app verdicts are commit statuses (`get_status`), and neither read shows the other. On a Chromatic repo read both (see *Reading CI / PR state in autonomous runs*).
- A brand-new workflow (present only on a PR branch, not yet on `main`) cannot be triggered via `workflow_dispatch` — the API 404s it, since GitHub only dispatches workflows on the default branch. Pre-merge evidence for a new job needs `pull_request` as a trigger, or a post-merge run linked back (see *Pre-merge evidence for a brand-new workflow*).
- A `pull_request` run builds the **merge ref** (head merged with base) while a `workflow_dispatch` run builds the **branch head** — so a CI red that will not reproduce locally is a moved base until `git log $(git merge-base HEAD origin/main)..origin/main` says otherwise, zero `pull_request` runs with `mergeable_state: dirty` is the conflict gate working rather than a platform fault, and a green dispatch run is evidence about neither the code nor a required check (APP-1901; see *A `pull_request` run tests the merge with `main`*).
- Repo code work is Forge's lane via the delivery loop — an interactive Cowork / Claude session holds no repo credentials of its own (it can attach a repo through the add-repo tool), so route a Forge ticket rather than attempt a `git clone` (see *Who touches a repo, from which surface*).
- A green PR stuck at `mergeable_state: unstable` on a Chromatic repo is usually the *"UI Tests"* pending-baseline status. **As of the 2026-08-13 Owner decision (APP-854) this is no longer a merge gate** — merge on the GitHub Actions check runs alone and do not route on a pending `"UI Tests"` status. (Pre-decision behaviour, retained for reinstatement: route to **In Review + `human`, assigned to Aled**, never Blocked — see *Chromatic*.)
- `create_pull_request` auto-attaches the PR to the linked Linear ticket, which may re-assign Aled; clear the assignee again after PR creation.
- **Linear's** `merge_diff` **refuses a draft PR and says only "Failed to merge pull request" — and Linear's** `mergeStatus: "ready"` **is not a statement about the draft flag.** `mergeStatus` describes mergeability (no conflicts, gates satisfied); the draft bit is a separate field and a draft PR reads `ready` on one while refusing to merge on the other. The error names no cause, so the natural reading is a conflict, a permission or a gate — and the actual fix is to mark the PR ready for review first. Read the draft flag explicitly before any merge call, from either surface, and where a PR has reached a merge attempt still in draft, un-draft it and continue (`skill-merge-pr` step 3 owns that as the residual case and counts the escape). This bites hardest **outside** the delivery loop: the loop's own chain un-drafts at QA on a clean pass, so a PR opened on a repo whose tickets are merged by hand never meets the leg that would have converted it and can sit in draft indefinitely while every readable signal says it is ready.
- New repo creation (via `create_repository`) is scoped to the `assoc-one` org; check `list_repos` first to avoid duplicates.
- A workflow **run** held at `action_required` (*"N workflows awaiting approval"*) is a permission gate in front of the run, not a slow run — the required check reads `Expected` forever and there is nothing to poll. Check for it before forcing a `synchronize`; a workflow that made the commit can approve its own runs through the API, otherwise it is the Owner's click (APP-1732; see *A workflow run can sit `action_required`*).
- Visual-regression baselines are **CI-rendered and committed back by a workflow** — a sandbox never writes one, because egress-blocked fonts and content and the dev-tools overlay make it render a different page, and it cannot fetch CI's `playwright-report` artifact either (APP-1717; see *Screenshot baselines are CI-rendered, never sandbox-rendered*).
- `document.fonts.check()` reads `true` for an **unregistered** family in the sandbox's pinned Chromium — iterate `document.fonts` and read each `FontFace.status`, and leave `.check()` to a CI-only test (APP-1731; see *CI coverage and the sandbox test environment*).
- The sandbox cannot delete a remote branch (`git push --delete` hangs up) and the GitHub MCP has no delete tool — prefer not to create a throwaway branch at all, and where one is unavoidable name it as residue for the Owner; *Automatically delete head branches* covers merged PRs only, never a closed-unmerged one (APP-1724; see *Branch naming*).
- **On `ENOSPC` in an unattended run, the diagnostic tools fail with the same message as the work did.** Once the harness's temp filesystem is full it cannot capture a command's stdout, so `df`, `du` and even a `CLAUDE_CODE_TMPDIR` export all return "the temp filesystem … is full (0MB free)" rather than answering, and the obvious next move — re-running the failed `npm install` — makes it worse. Read the signature: the identical message on a command that cannot itself consume disk. Only commands producing no output still run (`rm -rf … >/dev/null 2>&1`). The cause is structural rather than any one leg's — a publish leg clones and installs both `claude-ops` and `agents-site`, the two-build render control (`skill-ops-sync`) roughly doubles the site half, and nothing reclaims it at leg end, so a long queue accumulates every leg's tree. Reclaiming a *sibling* leg's scratch is an emergency move, safe only while the driver runs its legs strictly serially; take it if you must, and say so. (APP-1310.)
- Billed minutes are part of standing up or changing a workflow — every `pull_request` workflow carries `concurrency: { group: "${{ github.workflow }}-${{ github.ref }}", cancel-in-progress: true }` (excepting workflows on `main` or a tag, and workflows that commit their own output), and a ticket that adds matrix legs or materially lengthens a workflow states its per-PR billed-minute impact, before and after, as a criterion (APP-1902; see *Billed minutes are part of standing up or changing a workflow*).
- A workflow whose `pull_request` trigger is filtered to the default branch does not run on a **stacked** PR (one based on another PR's head), so the stack's only checks are the base-agnostic ones and a short check list reads like a short CI rather than an absent one — leave the `pull_request` trigger unfiltered when standing up CI, read a stacked PR's check list before treating the stack as gated, and **never merge a stacked PR into its base PR to acquire a gate**: re-base it onto the default branch, or state in the PR body that it is gated only through the base PR and name that run (APP-2037; see *A `pull_request` trigger filtered to `main` leaves a stacked PR ungated*).
- Adding, removing or reordering a section on a fixture page that stacks **element** screenshots re-rounds the baselines of every section after it by a pixel — a one-pixel red on untouched neighbours, identical across retries and across every Playwright project, is that coupling before it is a regression, so a fixture-section edit budgets the update-snapshots step up front (APP-2062; see *Screenshot baselines are CI-rendered, never sandbox-rendered*).
