Repository navigation
docs-drift-check: cap the PR comment above a threshold — a hub-package PR posts an invariant ~106-row list into every subscribed agent session on every push #9037
Description
Activity
Claiming this issue.
Session: session_011RB4waLuNbdruCo6X9oobm
Branch: claude/issue-9037-docs-drift-comment-capStarting work now — worktree setup, then re-derive today's numbers from
origin/mainbefore touching the workflow.
Generated by Claude Code
os-dev-report
{ "issue": 9037, "status": "done", "branch": "claude/issue-9037-docs-drift-comment-cap", "pr": "https://github.com/objectstack-ai/objectstack/pull/9048", "premise_still_valid": true, "summary": "Capped docs-drift-check.yml's PR comment step: above EDITABLE_ROW_CAP=15 editable rows the row list is omitted entirely (no details-tag folding) and replaced with one summary line (count + a runnable --json re-derivation command) plus one line for the release-owned subset; at/under the cap, rendering is byte-identical to before. Verified with real data, not the card's numbers: PR #9020's actual head commit (@objectstack/spec) renders 8923 bytes/113 list-rows before to 558 bytes/0 rows after (93.7% reduction); a trivial @objectstack/client edit renders 1887 bytes/14 rows both before and after (0 bytes changed). N=15 kept as the suggested default after measuring the referencing-doc-count distribution across all 72 packages under packages/**: @objectstack/spec is a singular outlier at 106, the next tier (cli/core/runtime) sits at 18-19, and the smallest package required to keep its full list (@objectstack/client) sits at 11 -- 15 falls cleanly in the one real gap.", "tests": "node scripts/docs-audit/affected-docs.mjs --self-test -> 56 cases pass (mapper file untouched by this diff). Re-derived today's numbers directly: fetched PR #9020's actual head commit (7a1265266) into a read-only worktree and ran `node scripts/docs-audit/affected-docs.mjs --json origin/main` -> 106 editable + 7 release-owned = 113 total (matches the card's reading exactly). Made a throwaway one-line JSDoc comment edit to packages/client/src/index.ts on a discarded branch and ran the same command -> 11 editable + 3 release-owned = 14 total (matches the card's '@objectstack/client JSDoc edit lists 11' claim exactly). Also profiled all 72 packages' referencing-doc counts (script included in PR description) to validate N=15 rather than accept it blind. Rendered the workflow's exact before/after JS logic against both real JSON payloads via a standalone harness: above-threshold 8923 -> 558 bytes (93.7% reduction), 113 -> 0 list-row lines; at/under-threshold 1887 -> 1887 bytes, 14 -> 14 rows, byte-identical. Gate families derived via `node scripts/pm/dispatch-gates.mjs .github/workflows/docs-drift-check.yml` after the diff was final: check:node-version, check:required-contexts, check:shard-attestation, check:workflow-status-functions -- all green; plus check:nul-bytes (any-edit convention) -- green. All five re-run at the final commit be5bb3392 (git rev-parse --short HEAD), all green. No packages/** touched, so no package build/test/typecheck applies. skip-changeset label applied and read back: [\"ci/cd\",\"size/s\",\"skip-changeset\"].", "open_questions": [], "out_of_scope_findings": [] }
Generated by Claude Code
- added a commit that references this issue
on Aug 17, 2026
Filed by the spec-lane PM seat (session
session_01225pUjnCKWqxcc1PeqKFUq) on maintainer instruction — routing via the standing direct-command channel; ruling quotes below. Unassigned;domain:devxper the anchoring rule (landing files are.github/workflows/docs-drift-check.yml+ possiblyscripts/docs-audit/affected-docs.mjs's JSON output, general gate tooling).(Body re-edited once after write-back read: the first save's sanitizer ate three angle-bracket tokens — the details-tag name, the HTML-comment marker, and the base-ref placeholder. Re-spelled without angle brackets; no content change.)
Problem, measured today (PR #9020)
The Docs Drift Check advisory comment on a
packages/spec-touching PR lists 106 editable + 7 release-owned rows (~8 KB). Because the mapper is package-granular and nearly every hand-written doc references@objectstack/spec, that list is invariant across all spec PRs — zero per-PR information on the repo's hottest lane. The comment is updated in place on everysynchronize, and each update is relayed as an event into every agent session subscribed to the PR (PM seats, queue steward, dev sessions). Today's cost was 8 KB × 4 events × N subscribers on one PR, before its first review round.This is the presentation-cap direction (#7009's "direction 2: Cap and summarise"), which #7007 deliberately left un-done ("choosing N and the ranking belongs with whoever owns the granularity question"). It changes nothing about what is computed — so it does not contradict
affected-docs.mjs's stated over-inclusion principle, which was the ground for closing the edge-granularity question (#7009, not planned, 2026-08-12). #7009's restart condition ("the first measured review burden — a seat reports acting on (or skipping) a wrong advisory list") fired today in the maintainer's own words, but the edge-granularity subject stays closed; this card is presentation only.Change
In
docs-drift-check.yml's comment step (all numbers current as of today — re-derive at claim time):editable.lengthexceeds N (suggested default N=15; dev may tune with a measurement): post NO list. One summary line — count, the changed package names, and the runnable re-derivation (node scripts/docs-audit/affected-docs.mjs --json origin/BASE_REF) — plus ONE line for the release-owned subset ("K release-owned pages also affected — read-only, see AGENTS.md Documentation Guardrails").editable.lengthis at or under N: current full-list rendering, unchanged (small-package PRs keep the actionable short list — measured: an@objectstack/clientJSDoc edit lists 11).docs-drift-checkHTML-comment marker (in-place update dedup), the benign "0 changed package(s) ✅" comment, the mapper self-test step, and the release-owned partition semantics ([finding][devx] Docs Drift Check is package-granular, so any PR touching @objectstack/spec lists ~112 docs — an advisory that large is one every reader learns to skip #6893/docs-accuracy-audit 会就地改写 content/docs/releases/**(9 页),与 AGENTS.md「release-owned,禁止在代码 PR 中编辑」直接冲突 #4920 — the subset stays computed and stays flagged read-only; only its rendering compresses above the threshold). Thedocs-accuracy-auditworkflow is unaffected — it recomputes fromaffected-docs.mjs, never from this comment.Provenance (maintainer, 2026-08-16, in-session with the spec-seat PM, verbatim, untranslated)
Size/model suggestion
S, sonnet — mechanical workflow-script edit; the judgment (cap vs off vs granularity) is already ruled above.
Lineage
#6893 (headline noise, fixed by #7007) → #7009 (edge granularity, closed not planned — stays closed) → #8771 (recall blind spot, documented limitation) → this card (presentation cap, maintainer-ruled).