Re-runnable consumer-relevance census over merged PRs

Context

A deployment stakeholder looking at this repository faces ~2500 merged PRs over ~5 months. The question they actually hold — "how many of these matter for our deployment?" — is unanswerable by reading: a model can scan PR titles in one session, not bodies, and a human cannot scan either. Today the only available answer is a gut estimate. Perception follows legibility; unreadable volume reads as noise regardless of its true relevance share.

The Problem

Relevance-by-reading does not scale, but relevance-by-graph does: every agent PR carries a newline-isolated Resolves #N; tickets carry epics, labels, and subsystem context; the archive under resources/content/ holds all of it locally. The question decomposes mechanically. What is missing is only the instrument.

Premise boundary (operator-challenged at creation, accepted): the SINGLE-NUMBER form of the question — "X% of PRs matter" — is genuinely unanswerable, because it requires counterfactual necessity judgment (would the deployment work without PR N?), which no mechanical walk can deliver. This census therefore claims NO relevance percentage. Its deliverable is the distribution over auditable membership buckets plus the editable mapping — classification by what a PR touches (mechanical), never by whether it was needed (judgment, explicitly the reader's). A stakeholder walk-through at creation time classified six representative subsystems fluently under exactly this taxonomy while correctly rejecting the single number — the taxonomy survives contact; the compression does not.

The Architectural Reality

• Sibling precedent: ai/scripts/diagnostics/planePlacementCensus.mjs + the re-runnable census pattern from PR #15836 (regenerates rather than freezes — a stale number cannot be quoted).
• Data sources, all local: resources/content/issues/** + archive (close-targets, labels, epic parentage), git log merge history (PR numbers, dates, subjects).
• Consumer taxonomy (the classification the census emits, three-way + one temporal tag):
  1. consumer-direct — runtime surfaces a deployment consumes (MCP servers, orchestrator, transports, GraphRAG/Memory Core runtime, deployment/compose, the app engine incl. grid/store/docking). Carries a per-subsystem temporal tag: now vs future-direct (a surface built for consumers whose adoption lies ahead — e.g. fleet-management tooling — is direct work, honestly tagged as not-yet-consumed).
  2. consumer-enabling — velocity multipliers whose payoff reaches consumers indirectly (CI/test infra, lints/gates, agent substrate, MX-loop/skill machinery, team-facing workflow servers a given deployment does not run itself, nightshift/dream machinery). These LOOK least relevant from outside and are precisely why the share must be measured, not guessed — an enabler's value claim is "boosts the team that ships your direct work," which the distribution makes visible instead of asserting.
  3. internal-only — portal/examples/docs-internal, culture artifacts with no consumer path.

The Fix (one PR)

A census script (sibling-lifted beside planePlacementCensus.mjs) that walks merged PRs over a date range, resolves each to its close-target ticket → labels/epic → subsystem bucket, and emits a dated markdown + JSON report: totals per bucket, per-month trend, unclassifiable remainder listed honestly (PRs without clean close-targets get a named unclassified row, never silent omission). Classification rules live in a documented, editable mapping (subsystem → bucket) so the taxonomy is auditable and adjustable — rule-not-instance, the census re-runs after every mapping change.

Acceptance Criteria

• Census script emits the three-bucket + temporal-tag report over a configurable merged-date range; re-runnable, dated, deterministic for a fixed range + mapping.
• No single relevance percentage anywhere in the output — the deliverable is the distribution + the mapping; any "X% matter" compression is a spec violation, not a summary.
• Premise falsifier (seed fixtures): the mapping ships with six representative subsystem judgments recorded at creation time (fleet tooling = direct/future; agent-cloud + docking + MCP runtime + grid/store = direct/now; team-facing workflow server + dream/nightshift + skill machinery = enabling) — the mechanical membership walk must reproduce them. If membership cannot reproduce fluent human classification, the premise fails and this ticket retires by its own test.
• Mapping file documented; changing it and re-running is the sanctioned way to contest a classification.
• unclassified is a first-class honest bucket with the PR list attached.
• One generated report committed as the exemplar (range: last ~5 months). Amended 2026-07-25 (operator direction): the generator + the pinned exemplar window (REPORT_WINDOW) reproduce the report on demand; generated reports are gitignored — derived data is never committed.
• Output is stakeholder-readable in one page (distribution + trend), with the full per-PR table as an appendix artifact.

Out of Scope

Counterfactual necessity ("would the deployment work without PR N?") — permanently out, not deferred: it is judgment, and the census is membership. Any judgment about what a specific consumer SHOULD care about (the mapping is editable precisely so stakeholders can encode their own view); release-notes generation (sibling consumer, separate lane); public marketing surfaces.

Decision Record impact

none — diagnostic script + generated report; no runtime surface.

Related

#15836 / PR pattern (re-runnable census) · #15835 · the traction/export-metrics lane · release-notes epics as a downstream consumer.

Live latest-open sweep: checked latest 15 open + KB semantic at 2026-07-24T23:17Z; nearest hits (skill-manifest budgets #11319, concept ontology #10030, golden-path convergence #14581) are different mechanisms; no equivalent found.

Origin Session ID: fed0f707-b481-432f-a5d9-587cc0325942 Retrieval Hint: query_raw_memories("merged PR relevance census three bucket consumer direct enabling internal mapping")

Authored by Clio (@neo-fable-clio, Fable). 📜