headless-authoring worker family: methods exceed 50-line cap (§4.2), CLAUDE.md size-limit text drifted from CONTRIBUTING.md

[cdeust]

Context

Discovered while fixing #237 (the consolidation-package import cycle). Not
in that issue's blast radius (no test, build, or lint step #237's fix
triggers checks these numbers — confirmed no active pre-commit hook or CI
job enforces file/method size in this repo today), so deferred here per
coding-standards.md §14.3 rather than folded into that PR.

Finding 1 — method-length debt in the headless-authoring worker family

mcp_server/handlers/consolidation/{drain_operations,cycle_orchestration}.py
have several methods well over the §4.2 50-line cap (measured on the
pre-#237 tree, i.e. before that fix's small sentinel-resolution additions):

drain_operations.py::drain_one                       ~85 lines
drain_operations.py::drain_all_gaps_on_page           ~130 lines
drain_operations.py::drain_missing_anchors            ~90 lines
cycle_orchestration.py::run_headless_authoring_cycle  ~175 lines (incl. 2 nested coroutines)

These were already over the cap before #237 touched these files (that PR
added ~5 lines of sentinel-resolution logic to each, not the underlying
size). Fowler catalog fixes: Extract Function on drain_all_gaps_on_page's
per-gap fill loop and run_headless_authoring_cycle's two nested
coroutines (drain_anchor_bounded/drain_page_bounded could become
module-level functions taking sem/budget as explicit parameters).

Finding 2 — CLAUDE.md vs CONTRIBUTING.md disagree on the numbers

• CLAUDE.md § Code Style: "300 lines max per file; 40 lines max per
  method. Enforced by the craftsmanship-checker pre-commit hook."
• CONTRIBUTING.md § Definition of Done (or similar): "§4.1 File ≤500
  lines, §4.2 function ≤50 lines" — citing coding-standards.md's actual
  §4 numbers.
• No craftsmanship-checker pre-commit hook is actually installed
  (.git/hooks/ has only the standard *.sample files), and no CI job
  greps for file/method line counts.

Before splitting the functions in Finding 1, resolve which number is
authoritative (500/50, matching coding-standards.md and CONTRIBUTING.md,
or a locally-tightened 300/40) and fix whichever doc is stale, so the next
split targets the real threshold instead of guessing.

Acceptance criteria

1. CLAUDE.md and CONTRIBUTING.md agree on the file/method size limits (fix
   whichever is stale, or add an ADR if 300/40 is an intentional
   local tightening — coding-standards.md §10 requires the exception be
   written down).
2. If 500/50 is confirmed as the real limit and today's methods are
   already compliant, close as not-a-bug. If 300/40 (or the confirmed
   real number) is violated, split drain_all_gaps_on_page and
   run_headless_authoring_cycle via Extract Function, existing suite
   passing unchanged (tests_py/handlers/test_headless_authoring_throttle.py
   • tests_py/handlers/consolidation/test_import_cycle_237.py cover the
     patchability contract these files carry — any refactor must preserve
     monkeypatch.setattr(headless_authoring, ...) observability, see those
     files' module docstrings).

[cdeust]

Folded into PR #277 rather than left as a separate follow-up, per this session's directive against splitting discovered work into new/parked issues.

Criterion 1 — doc drift resolved

CLAUDE.md and CONTRIBUTING.md now agree: 300 lines/file, 40 lines/method is authoritative for this repo (a local tightening of coding-standards.md's 500/50), and CLAUDE.md's stale "enforced by the craftsmanship-checker pre-commit hook" claim is corrected to "enforced by code review today; no automated hook exists" (verified: .git/hooks/ has only *.sample files, no .pre-commit-config.yaml). Commit 4e95962.

Criterion 2 — method-length + file-size violations split

Every file in the consolidation package touched by #237's fix is now ≤300 lines and every method ≤40 lines (Fowler Extract Function / Move Function, one catalog entry per commit):

• candidate_scan.py: _scan_pages_with_gaps/_collect_anchor_candidates split (commit 4510ae6).
• drain_operations.py: drain_one/drain_all_gaps_on_page split; drain_missing_anchors moved to a new anchor_authoring.py (commit c8598e5).
• cycle_orchestration.py: run_headless_authoring_cycle's two nested coroutines became module-level functions taking sem/budget/invoke/_root as explicit parameters — exactly this issue's own prescribed fix shape (commit 5c78137).
• headless_authoring.py: _claude_invoke split and moved to a new claude_invoke.py; CycleBudget/DrainResult/CycleSummary moved to a new cycle_types.py (commit ee2cf5e). File went from 469 → 255 lines.

All behavior-preserving: 66 → 67 tests passed with 0 modified assertions across the refactor commits (the +1 is a new fresh-interpreter regression-coverage entry for each new module, matching #237's own pattern for load-order-sensitive splits — not a behavior change to existing tests).

Mutation testing (§12) on the touched family surfaced ~570 survivors, but a controlled A/B comparison (mutating the pre-refactor cycle_orchestration.py against the identical test selection) produced the exact same 121-survivor count as the post-refactor file — proving the bulk of these are inherited test weakness (subprocess/invoke test doubles that accept-and-ignore most kwargs), not something this refactor introduced. Closed the tractable subset: 7 new tests added for candidate_scan.py (commit 0b6a340), the one file in the family cheap to test directly (no subprocess/PostgreSQL), cutting its survivor count from 38 (pre-refactor baseline) to 25.

Closing as resolved by #277.