docs(development): cut the agent process playbooks to repo deltas (Q886, Q887)

[karlkfi]

Closes Q886 and Q887.

The dispatch and backlog process lives in three globally-installed skills — session-orchestrator, session-worker, session-backlog. Both agent process playbooks carried a second copy of it, written back when the docs had to stand alone without the private skills. Two copies of a process that is still being iterated is what Q886 predicted would drift, and it had.

Q886 — the audit

Compared both playbooks against the three skills as installed, read through the Skill tool so the comparison is against shipped text rather than a remembered version. The findings split into stale (the doc contradicts the skill, or itself) and duplicate (the doc restates what the skill owns). Only the first class is a defect on its own.

Stale, all in parallel-dispatch.md:

Site	What it said	What is true
line 3	"a single dispatcher session that merges each PR after its checks pass"	No agent merges. Line 315 and session-orchestrator §6 both said so. The row named this one.
lines 22, 24	the /goal template told the dispatcher to "give every worker the self-healing contract" and to restate the isolated-commit rule	Lines 217–221 of the same file, and session-orchestrator §2, forbid restating the contract in a spawn prompt. The template predates that rule and was never re-read against it.
line 156	"The earlier contract ran a distinct background conflict-watcher"	Change narration about a contract no current reader ever followed.
lines 409–412	"The earlier rule was 'the dispatcher owns the coordination files.'"	Same class: a superseded rule kept as history.

session-backlog had no stale counterpart. maintaining-backlog.md correctly documents the single-table layout. The skill now describes a per-item store as a destination, and no cutover has landed on main, so describing the store would have been the mistake parallel-dispatch.md already records under § Coordination channels. The page now says so explicitly.

Q887 — the cut

Both playbooks now carry this repo's deltas and nothing else: the gate and its sub-gates, the throttle, the merge queue and allow_auto_merge: false, the scripts/agent/ tooling, the hooks, the caps, the ID allocator, the merge drivers, and every measurement taken here.

• parallel-dispatch.md 612 → ~420
• maintaining-backlog.md 796 → ~790

That asymmetry is the finding, not a shortfall. The row measured the skill retirement adding 21 lines to the first file and 4 to the second, and re-reading section by section confirms why: maintaining-backlog.md is almost entirely repo mechanism and repo measurement already. The only real duplication was § The shared process, in brief, which restated position-is-priority, the two Queue states, the blocker syntax, the Notes cap, the \| rule, the Deferred trigger tags, and plan docs for M/L. That section is now § Where the format differs from the skill and keeps only what the skill does not say.

Upstream moved mid-branch, so this folds it in

karlkfi/claude-skills#71 merged 35 minutes after this branch's audit ran, adding a "What is this batch for?" section to session-orchestrator: the dispatcher now asks for the release theme before selecting anything, splitting it into a ceiling that excludes and an emphasis that sorts.

That obsoletes a section this branch had deliberately kept — § "Priority is release-thematic, and the Queue does not record the theme", which asserted the problem was unsolved and told the maintainer to state the theme in the /goal scope. Shipping it would have landed a fresh instance of Q886's own defect on the page the PR exists to de-drift, so it is folded in here rather than filed as a follow-up.

The replacement says what each half means here:

• The ceiling is post-1.0 SemVer. The skill defers the versioning question rather than hardcoding one, and release.md § Patch releases and backports is this project's answer, including the backport-branch exception the skill says selection must never volunteer.
• A scoped release records its own ceiling durably. The skill holds the theme for the run and writes it nowhere, which is right for an emphasis but does not describe what happens here: a scoped release already has a plan doc and X.Y-gate labels naming what the tag waits for. Read it rather than asking again.
• The emphases that recur here — parity work, the cleanup tail, and the release harness that gates a tag without being what anyone upgrades for.

Two references to the renamed anchor were updated with it (the /goal knob and the pre-flight checklist), both of which had told the maintainer to pre-state a theme the dispatcher now asks for.

SemVer is contributor process, not agent process

So it does not get cut to a delta. release.md already writes it out, which is the right home — but the place a contributor decides whether a row belongs to a release is maintaining-backlog.md § Don't pre-assign release versions, and that never linked it. It does now: a patch is bugfix-only, so labelling a feature row for one is wrong however badly the release wants it, and the way out is a backport branch rather than a relabel.

The claim the cut invalidated

Three places asserted that a contributor without the skills loses nothing because every rule is written out in this tree in full. The cut makes that false, so all three are corrected rather than one:

• skills.md — the section is now split by class. Working-method skills (deslop, verify-claims, rendered-page-review, tech-docs-layers, github-issue-filer, session-retro) still cost a contributor nothing. The three process skills own their process, and what holds the rules for a reader without them is that the tooling is in-tree and gate-enforced, where the prose is not: lint-backlog.sh, the ID allocator, the merge drivers, check-status-isolation.sh and the dispatch hooks all run in make check and the pre-commit hook regardless. It also names the reader this trades away, and what would reverse the trade.

  An earlier revision of this branch said "vendored", which reads the dependency backwards and was corrected at all three sites that used it, including one that predates this PR. The five tools named were written here, and the session-backlog skill has no counterpart for most of them: its bundled lint is bash over a smaller generic rule set where devtools/docs/backloglint is Go with 13 rules over a GFM AST. The claim itself is unaffected — every tool it names is in that set — but the direction of the borrowing matters, because it is the first thing someone checks when asking whether the docs can lean on the tooling.

• docs/development/README.md — both index rows restated the old claim and the old scope.

• documentation-standards.md — its skill-linking rule cited maintaining-backlog.md as the worked example of a page kept sufficient for a contributor without the skill, which is now exactly what that page is not. It points at the class distinction instead and keeps testing.md § Diagnosing failures as the example that still holds.

Also in the diff

scripts/docs/em-dash-baseline.txt ratchets both files down (121 → 112, 92 → 39). The baseline is a ceiling, so leaving parallel-dispatch.md at 92 against an actual 39 would have let 53 em-dashes back in silently. Counts are the checker's own, from check-em-dash.sh --report, not a grep. The ratchet then caught the fold-in above at 42 and the new prose was rewritten to fit rather than the ceiling loosened.

Flagged, not acted on

/goal (three sites) and /autofix-pr (one) are harness features rather than skills, and nothing in the repo defines either. Neither appears in this session's command list, but that list is session-scoped, so absence here is not evidence they are retired — and neither row is about them. Left as-is rather than rewritten on a guess.

Testing

• make check green over the final tree, rebased onto current main. The sub-gates this change can fail all report ok by name: doc-links, lint-backlog, status-isolation-check, plan-index-check, no-plan-refs-check, em-dash-check, roadmap-check.
• Every anchor with an inbound reference was enumerated before the cut (7 into parallel-dispatch.md, 18 into maintaining-backlog.md) and every one survives; the sections that went had no inbound links.
• One link written during the cut pointed at STATUS.md#Q869, whose row lives on draft docs(plan): plan a per-item queue store with a computed priority order (Q869) #1534 and not on main — caught before committing rather than left for the gate.
• Closing cascade checked for both rows: no roadmap annotation, no plan doc, no STATUS.md#Q886/#Q887 anchor anywhere, and the only Blocked by reference was Q887's own to Q886, deleted with it.