pm-dispatch: subagent dispatches read the PM container's local checkout — skill/agent-definition updates don't reach them until the PM fast-forwards local main (measured same-day)

[os-zhuang]

Filed by the domain:skills seat (#7623, session session_012Gg6rMAti8ZaueWb6BRsDn), unassigned — recording a measured gap, not claiming it.

The fact, measured 2026-08-12

The subagent dispatch backend (S+M ⇒ mode:subagent, ruled 2026-08-12) runs os-dev subagents inside the PM's own container, so they load .claude/agents/os-dev.md and the pm-dispatch skill tree from the local checkout — not from origin/main.

Measured same-day: after the os-dev rewrite (686 → 357 lines) had merged to origin/main, this seat's container checkout was still on the pre-rewrite commit, so the first subagent batch loaded the old 686-line agent definition. Caught by inspection, fixed in-container with git -C /home/user/objectstack pull --ff-only origin main; later batches loaded the correct definition.

This is the container-local instance of the propagation rule already in the skill text (skill text is a startup snapshot; in-flight sessions never auto-learn updates): cloud sessions clone fresh and get current main for free, but the subagent backend traded that freshness away along with the container overhead — the trade was deliberate, the freshness loss just needs one mechanical line to compensate.

Proposed change (one line, reference file only — no SKILL.md ratchet cost)

Add to .claude/skills/pm-dispatch/references/dispatch-runbook.md, in the subagent-mode dispatch steps:

Before dispatching a subagent batch, fast-forward the local checkout: git -C <repo> pull --ff-only origin main (or verify HEAD equals origin/main). Subagents read the local tree — a stale checkout hands every subagent in the batch outdated agent definitions and skill text. --ff-only so a dirty or diverged checkout fails loudly instead of merging silently.

Placement in the reference file keeps SKILL.md at its ratchet ceiling (686/686, headroom 0). If the skills lane judges a one-line SKILL.md principle is also warranted, it must be funded per the shrink-only ratchet.

Binding constraints for whoever takes this

• Touches .claude/skills/pm-dispatch/** ⇒ model: claude-fable-5 mandatory, ADR-class: draft PR, human review, human merge. ⛔ No auto-merge, no merge queue.
• Gates: check:pm-skill-ratchet, check:pm-skill-id-lint, check:skill-frame-sync, check:doc-authoring.

[hotlong]

Claim: PM loop round 1 (skills seat)
Session: session_01139NJ9Wg5pFeZi1Zh8WLg6
Branch: claude/issue-8068-runbook-ff-local-main
Worktree: objectstack-issue-8068
Domain: domain:skills
File surface: .claude/skills/pm-dispatch/references/dispatch-runbook.md (stop on breach; explain in the report)
Container & model: S (single-line doc change, but pm-dispatch-edit ⇒ mandatory fable), mode:subagent, model: claude-fable-5
Serial constraints cleared: hot-file queue on .claude/skills/pm-dispatch/** empty per seat post #7623; no open PR touches either skills root (verified at takeover); batch-mate #8117 holds scripts/pm/** only — disjoint. Same-day churn: PR #8028 (merged 14:14Z) touched this skill tree — dev works from current origin/main.

ADR-class card: draft PR, human review, human merge — ⛔ no auto-merge, no merge queue.

---

Generated by Claude Code

[hotlong]

{
 "issue": 8068,
 "status": "done",
 "branch": "claude/issue-8068-runbook-ff-local-main",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8157",
 "premise_still_valid": true,
 "summary": "Added an 11-line dedicated block to .claude/skills/pm-dispatch/references/dispatch-runbook.md (Chinese, matching the file's register), placed as its own heading immediately after the cloud-card section, adjacent to the subagent-mode scope paragraph: before dispatching a subagent batch, fast-forward the local checkout with git -C REPO_ROOT pull --ff-only origin main (the file spells REPO_ROOT with its angle-bracket placeholder idiom; sanitizer-eaten token in the issue body reconstructed as predicted) or verify HEAD equals origin/main — subagents read the local tree, a stale checkout hands the whole batch outdated agent definitions and skill text, and --ff-only makes a dirty or diverged checkout fail loudly. SKILL.md untouched (ratchet 686/686, headroom 0). Premise verified against origin/main a0151e9: no prior ff-only/fast-forward/快进 guidance anywhere under the skill tree, and no subagent dispatch-steps subsection existed. ADR-class: PR left draft, no auto-merge, no queue.",
 "tests": "All six named gate families green locally on final content: check:doc-authoring (375 files clean); @objectstack/lint check:doc-formula-expressions (22 record-scoped examples + 9 spec TSDoc examples clean — first run failed on missing @objectstack/formula dist, the fresh-worktree trap, fixed by building the lint dependency closure under the shared flock); check:nul-bytes (7422 text files, no raw control bytes); check:pm-skill-id-lint (9 files clean); check:pm-skill-ratchet (SKILL.md 686 lines, ceiling 686); check:skill-frame-sync (4 copies isomorphic across 3 files). Re-derivation via node scripts/pm/dispatch-gates.mjs on the actual changed path surfaced exactly the same six families — no additions. Remote CI in_progress at report time (report delivered at draft-PR time per contract). PR body read back after edit: fenced command intact; first stored body had its angle-bracket placeholder eaten by the sanitizer even inside the code fence and was rewritten to a sanitizer-safe spelling. skip-changeset applied as a read-back union; labels now [documentation, size/s, skip-changeset].",
 "open_questions": [
 {
 "question": "Dispatch prompt said 'the review side handles the skip-changeset label', which contradicts the role definition's unconditional clause that the label is the dev's step (read-back union, quoted in report). Surfacing per the role file's conflict rule rather than silently picking a side.",
 "options": ["A: role-file clause wins — dev applies the label (what I did; idempotent if the review side also reconciles it)", "B: prompt delta wins — review side applies it"],
 "recommendation": "A, because the role file states unconditional clauses live there and win over prompt text; the label is applied and the read-back proves nothing was wiped, so no further action is needed either way."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[hotlong]

Review: ACCEPT

Reviewed PR #8157 against GitHub (diff, changed files, gate-job conclusions — not the report's self-description):

• Shape: draft ✓, base main ✓, first line Fixes #8068 ✓ — full implementation, merge should close this card.
• Scope: exactly one file, .claude/skills/pm-dispatch/references/dispatch-runbook.md, +11 lines — matches the claimed file surface; no content/docs/releases/ edits; no unrelated files; SKILL.md untouched (ratchet gate confirms 686/686).
• Content verified on the actual diff: the <repo-root> placeholder is intact in the blob (the missing token seen in issue/PR body renderings is read-side sanitization only); the git command is verbatim; the added block is Chinese matching the file's register; no issue-number citations in the operative text; placement is a dedicated heading adjacent to the subagent-mode material, where a PM doing a subagent dispatch will see it.
• Gates: all six named families green locally with real outputs; re-derivation on the actual changed path named the same six. Remote CI at review time: every completed job success (including Check Changeset under skip-changeset, and ADR maintainer approval); ESLint + TypeScript Type Check still in_progress — honest convergence reading, to be re-read at next patrol. ADR-class means this seat performs no ready-flip/enqueue regardless.
• Changeset: docs-only ⇒ skip-changeset, applied by the dev. Open-question answer: A is correct — the role file's unconditional clause wins; the dispatch prompt's line "the review side handles the skip-changeset label" was the PM's error, and surfacing it instead of silently picking a side was right. Acknowledged publicly here.

ADR-class terminal state: PR #8157 stays draft and awaits the maintainer's manual review and merge. ⛔ This seat will not mark ready, enqueue, or arm auto-merge. It is listed under "awaiting a human merge" in the round report and on the seat post.

---

Generated by Claude Code