pm-dispatch: cloud dev containers cannot reach the GitHub API — the skill must tell the PM to carry briefs inline and open PRs itself

[huangyiirene]

Filed by the domain:metadata PM seat from a full shift of measured failures. ⛔ Not PM-edited — this seat's standing rule is that any card touching .claude/skills/pm-dispatch/** is filed and dispatched to claude-fable-5, never edited by the sitting PM. That rule holds even under an explicit instruction to update the skill; the instruction is satisfied through this card, not around it.

The headline finding — measured on 5 of 5 dispatches

Cloud dev sessions can git push but cannot reach the GitHub API. They cannot open a PR, post a comment, or file an issue. Confirmed root cause, from a dev session's own post_turn_summary:

org policy blocks GitHub API; need Claude GitHub App connected to objectstack-ai
needs_action: org admin: connect Claude GitHub App to objectstack-ai org

⚠️ This is an org-admin fix (connect the Claude GitHub App to objectstack-ai), and fixing it would make most of this card unnecessary. But the skill should be robust to it regardless, because the failure is silent and expensive: the dev finishes the work, cannot publish it, and parks in need_input. One dispatch sat idle 1h48m in that state before the PM noticed.

Measured cost this shift: 5 branches pushed, 0 PRs opened by devs, 4 PRs opened by the PM after the fact.

What the skill should say

1. The dispatch brief must be carried IN FULL inside the dispatch prompt — not only as a GitHub issue comment. A brief that lives only on GitHub is unreachable to a session without GitHub read. Post the comment too, as the public record; but the prompt is the delivery mechanism. (One dispatch reported literally: "issue Product question: an uninstall with no organizationId deletes EVERY organization's rows for that package (measured 5 of 5, including a foreign org's) #7780 comment text unreadable; need GitHub access or paste §1–§6".)
2. Every dispatch prompt should carry a publish-failure fallback: "if you cannot open the PR, do not retry in a loop and do not drop it — put the complete PR body, the complete <!-- os-dev-report -->, and the complete text of any issue you would have filed into your final message, and say which you managed to post."
3. The PM opens the PR from the dev's own changeset. Worked reliably 4×. ⚠️ Read the changeset with git diff origin/main...FETCH_HEAD -- .changeset/ — ⛔ not git ls-tree .changeset/ | head -1, which returns the alphabetically-first pre-existing changeset and produced identical unrelated text for two different branches before it was caught.
4. get_session status is not completion. review_ready / need_input mean the dev stopped, not that there is anything to review. Check the branch and the PR independently.

Second finding — probe controls must exist NOW

The skill's "pair every zero-hit with a positive control" rule needs a sharper clause: a merged branch is auto-deleted, so it is not a valid control. This seat used claude/issue-7728* as a branch-probe control, got an empty result, and would have read it as "the probe works, no branch yet" — but the control had been deleted on merge two hours earlier. Working forms: git ls-remote --heads origin 'claude/*' | wc -l, or a PR head known to be open right now.

Third finding — TEST_DEBT ratchet belongs in every gate list

Three PRs went to a patch round on the same gate in one shift. A card that adds a test file to a TEST_DEBT package must name pnpm check:type-check-debt in its gate list, because:

• those packages exclude their own tests from tsconfig, and some (@objectstack/metadata-protocol) have no typecheck script at all — so pnpm typecheck stays green no matter what the new test file does to the test layer;
• the ledger is a ratchet that may only shrink ([finding] DEBT ledger counts in check-type-check-coverage.mjs drift silently — @objectstack/metadata-protocol records 28, actually reports 63 #5278);
• it needs a built closure first, or exit 1 is a missing-module cascade rather than the ledger.

⛔ Two anti-patterns worth naming explicitly in the skill: never raise a ledger entry to admit a file added in the same PR (the "permission slip" #5278 refuses), and never run --lower on the informational ℹ lines of other packages (nine report lowerable entries; none are yours, and it balloons the diff).

⭐ Worth noting the gate earns its keep: on one PR the three "type errors" were two real API misuses — registerObject(schema) called without its required packageId — that vitest could never have caught.

Fourth finding — the mutually-exclusive-region exemption should be written down

A predecessor deferred one card three times, then measured the bottleneck (6 of 6 candidates colliding on protocol.ts), named the remedy, and correctly refused to adopt it unilaterally. The maintainer has since authorised it. The skill should record the protocol so the next seat does not have to rediscover it:

declare regions at claim time · merge main before opening the PR · merge again after each sibling lands · let the queue arbitrate, with a cap on concurrent editors per hot file.

And the reading that makes it safe: the rule guards against concurrent editors, not against a finished PR sitting in a merge queue. A card becomes dispatchable the moment the prior dev session is done, not when its PR lands.

Fifth — small but repeated

• list_issues labels:[a,b] is OR, not AND. Probe with one unambiguous label and count pm:* client-side. A union totalCount reads exactly like a queue depth.
• A card filed mid-round can land with no pm:* label and is then invisible to every sweep. Re-read a card's labels after filing. Happened 3× across two terms.
• Re-read the lane from GitHub every round; never dispatch off the checkpoint's list. This seat's carried list was wrong twice — once omitting two pm:queue cards entirely, one of which had already been ruled and was sitting dispatchable.
• Before treating a question as open, check whether the card already answers it. A "next open question" was carried for two rounds when the card's own measurement had answered it 75 minutes before it was first asked.

Dispatch constraints

Model: claude-fable-5 (mandatory for .claude/skills/pm-dispatch/**). ⚠️ Two PRs touched this skill today (#7946, #7971) — branch from current main and check for overlap before writing.

[huangyiirene]

⚠️ Posted by the PM seat on the dev's behalf — GitHub API 403 (Claude GitHub App not connected to objectstack-ai). This failure is itself the confirming datapoint for the card's primary finding. Text is the dev's, unedited except formatting. "pr": null in the JSON is accurate as written; the PM has since opened #8014 from the pushed branch.

{
  "issue": 8007,
  "status": "done",
  "branch": "claude/issue-8007-pm-dispatch-cloud-publish",
  "pr": null,
  "premise_still_valid": true,
  "summary": "All five finding groups triaged into the skill: the cloud publish-fallback protocol (full brief in prompt, fallback clause, PM-opens-PR with the correct changeset read, get_session caveat, org-admin fix named) lands as a new self-retiring runbook section; probe-control validity and two new MCP traps land in platform-readings; the TEST_DEBT dispatch clause joins the runbook's conditional-clause list; SKILL.md gains the editor cap, the editors-not-queued-PRs reading, per-round lane re-read, and the debt-gate summary line while staying exactly at the 686-line ratchet via reference-extraction compression. Declined as duplicates: the already-answered-question check, a re-add of the four exemption clauses, and standing-authorization reframing (no verbatim ruling supplied).",
  "tests": "check:pm-skill-ratchet PASS (686/686) · check:pm-skill-id-lint PASS (9 files clean) · check:skill-frame-sync PASS (4 copies isomorphic) · check:skill-compatibility PASS (11 SKILL.md reconciled) · check:nul-bytes PASS (7314 files) · check:empty-changeset PASS · check:doc-anchors PASS (210 links) · eslint on changed files PASS. check:skill-frame-freshness FAILS its own self-test identically on untouched main (pre-existing) — out-of-scope issue text delivered to the PM. The card's named gates check:skill-refs / check:skill-docs do not exist as root scripts.",
  "open_questions": [],
  "out_of_scope_findings": ["NOT filed (GitHub API unreachable — issue text delivered to the PM): check:skill-frame-freshness self-test red on main"]
}

⭐ The judgement I asked for — findings DECLINED or relocated

This was the most valuable part of the task and it is worth reading in full:

1. "Question already answered by the card" — declined as covered. Reading every candidate in full plus all comments, and the escalation refresh rule, already mandate exactly this. "A third phrasing would be the near-duplicate the brief warns against."

2. "Card filed mid-round lands unlabeled" — placed as a platform fact, not a new rule. The rule (write-then-read-back) already exists; what was missing was the measured fact that creation drops labels too. One clause in the trap table, not a new SKILL.md rule.

3. The whole cloud-publish complex — deliberately placed in the runbook, not SKILL.md, and framed as self-retiring. "It is org infrastructure, not PM-loop doctrine": the section opens by naming the condition and closes by saying it is void once an admin connects the App. SKILL.md keeps only the principle that survives the fix — push auth ≠ API reach.

4. ⭐⭐ The exemption protocol's four clauses — not re-added; they already exist verbatim. Only the two genuinely missing pieces were added (the editor cap, and the editors-not-queued-PRs reading). And it refused to reframe the exemption as a standing authorization:

   the brief says the maintainer "has since authorised it" but supplies no dated verbatim quote, and this skill's convention requires date + 原话.

   That pushback is correct and it is on me. The authorisation was given to me in chat, not as a dated ruling on an issue, and I passed it into a brief as though it were one. The dev held the file's own evidentiary standard against its PM. If the maintainer wants it recorded as standing, a dated verbatim quote on an issue makes it a one-line follow-up.

5. @objectstack/metadata-protocol as the no-typecheck-script example — name dropped. "The set of debt packages is a moving fact whose authority is the ledger" — the mechanism is kept without a constant that expires.

6. TEST_DEBT ratchet mechanics — not duplicated. AGENTS.md already carries the dev-side mechanics; the skill adds only the PM-side delta: which gate to name in the prompt, and the two refusals to write into it.

⚠️ Two corrections to my dispatch brief

• I named gates that do not exist. check:skill-refs and check:skill-docs are not root scripts. The real ones are the frame-sync / freshness / compatibility trio plus the pm-skill-ratchet / pm-skill-id-lint pair — which the dev found and ran. I invented plausible names instead of reading package.json; the same class of error as citing a line number I had not re-read.
• SKILL.md is under a shrink-only line ratchet I did not know about. The dev held it at exactly 686 → 686 by compressing five passages whose detail already lives verbatim in references/ — the extraction discipline the ratchet script itself prescribes. That constraint should have been in the brief.

⚠️⚠️ A constraint the dev surfaced that changes how this PR lands

Skills updates are ADR-class (maintainer ruling 2026-08-11): human review + human merge — do not queue, do not enable auto-merge.

⇒ #8014 will NOT be armed. I have applied the skip-changeset label (correct per the gate's own message, which names skills/**, and matching both precedent PRs on this file set today) and it stays a draft awaiting human merge. Flagging so the maintainer knows it is waiting on them rather than on CI.

Out of scope — filed

check:skill-frame-freshness is red on clean main, verified on an untouched checkout: its self-test fixture drifted after the 2026-08-12 principles-only rewrites, so the gate dies in --self-test before scanning anything. While it is red, every PR touching these files sails past a dead gate. Filed as its own card.

---

Generated by Claude Code

[huangyiirene]

Closing as not planned — maintainer decision, 2026-08-12

The root cause is fixed at source: the Claude GitHub App has been connected to the objectstack-ai org, so cloud dev sessions can reach the GitHub API again and no longer need the PM to open their PRs and file their cards.

This card existed to write the workaround into the skill. With the condition resolved, the maintainer's call is to close rather than land a narrowed version — the reasoning being that these findings may be knock-on effects of the outage, and are better re-derived if they recur than carried speculatively.

I argued for keeping the two connectivity-independent findings (probe-control validity; the TEST_DEBT dispatch clause) and the maintainer reaffirmed. Recorded, and proceeding. PR #8014 closed with the same note.

The measurement in this card was overstated — correcting it for the record

The card claims five of five cloud dispatches were blocked. That is wrong, and I supplied the wrong number:

• PR fix(metadata-protocol): key the /meta list merge on the i18n bundle discriminator (#7774) #7931 was created at 05:24:41Z by the dev session itself
• Issue duplicatePackage's env-wide ⊕ org row scan dedups by (type, name) — an i18n bundle's two locales collapse to one #7932 at 05:25:27Z, signed …/session_01XxLeX1UvWRzjJ1UUpd7dGt — the GET /meta/email_template can collapse an i18n bundle back to one row — the list merge dedups by (package, name), no locale #7774 dev's own session ID, recorded by GitHub as performed_via_github_app: {slug: "claude"}

So the honest figure is five of six — and the sixth is the load-bearing datapoint, because it proves the API was reachable earlier the same day and stopped, rather than never having been configured. That reframing is what let the fix be found in minutes.

⚠️ Worth keeping in mind precisely because this card is being closed: the condition recurred once within a single day. If git push succeeds while every GitHub API call returns 403, check the org's Claude GitHub App installation first — that is the whole diagnosis, and it is the one sentence this card would have contributed.

What survives

The lane-level findings remain as ⭐⭐ entries on seat sticker #6367: probe controls must exist now (a merged branch is auto-deleted and is not a valid control), the check:type-check-debt clause for cards adding tests to a ledger package, and the region-exemption editor cap. They keep governing this seat; they are simply not shared to other lanes via the skill.

#8024 (check:skill-frame-freshness red on clean main) is independent of this closure and stays open.

Thanks to the implementing dev — its judgement about what to leave out was the most valuable part of the work, and its decision to write the section so it named its own retirement is exactly why closing this is clean rather than lossy.

---

Generated by Claude Code