The Body Cap Measures the Concept, Not Its Neighbours

[sameera]

Epic: The Body Cap Measures the Concept, Not Its Neighbours

Description

The concept store's 400-word body cap exists to keep each page cheap to load, because several
pages are loaded per planning or design task. It applies to the whole body — including
Integration Points, the prose list of a page's neighbours. Those two things grow by different
laws. A page's own content grows with the breadth of its concept, and "split, don't grow" is the
right answer there. Its neighbour list grows with the size of the store, and splitting is the
wrong answer: a narrow page cut in half to make room for someone else's bullet makes retrieval
worse, not better.

The store has grown from 14 seed pages to 48 and the cap has not moved, so the second law now
dominates. Twenty-nine of 47 active pages sit within 6 words of the cap and 13 sit exactly on it.
Integration Points accounts for 16% of all capped body text store-wide. The pages that are full
are the ones with the most neighbours, not the broadest ones — distiller carries 15 edges and
143 words of neighbour prose, leaving 257 for its own content (its Summary, How It Works and
Key Invariants — the term this epic uses throughout), while theme-tokens carries one edge and
has 383 words of its own. No page in the store exceeds 400 words on its own content; the maximum
is 383. Nothing is too broad. The cap is simply measuring the wrong thing.

The consequence is that the touches graph has stopped growing, silently. Reciprocity makes every
new edge cost prose on the neighbour too, an update may not compress still-true content to make
room, and splitting requires a retrieval seam the new work did not create — so the honest move is
to drop the edge and describe the relationship in prose instead. PR #219 did exactly that, for
three real interactions, and flagged it. Nothing fails when this happens; blast-radius retrieval
just quietly gets less complete, and it degrades first on the hub concepts new work most needs to
attach to. This epic re-cuts the cap so it bounds a concept's own content, bounds a neighbour list
by the size of each entry instead, and stops the drain from ever having to choose between a real
edge and the cap.

Success Metrics

• Every active concept page passes the validator with no edit to any page — the change is a
  measurement correction, not a migration.
• A drain that adds a touches edge to the store's highest-degree page completes with no
  split, no eviction, and no dropped edge.
• Worst-case single-page load is bounded by a stated formula over the cap, the per-bullet ceiling,
  and a page's degree — and the schema states the resulting per-task budget at the existing 5–7
  page retrieval cap.
• Each of the three pages PR distill: Backlog Stubs Become GitHub Issues (#185) #219 could not link into accepts a reciprocal bullet without a split,
  so the interactions it recorded as prose become declarable as touches edges.
• A page that is genuinely too broad on its own content still fails the cap and still triggers the
  split path.

Personas

Per docs/product/context.md.

Assumptions

• The quantity the cap protects is the per-task load — several pages loaded per task under the
  existing 5–7 page retrieval cap — not the size of any single page. Raising the worst-case page is
  acceptable as long as that budget is stated and bounded.
• No concept page is hand-edited by this epic. Pages change only through a drain, so the concept
  pages that themselves describe the cap are updated when this epic distills, not by hand.
• The 400 number is left alone. This epic changes what is counted, not how much is allowed.
• The validator's only consumer that gates on its result is the drain — there is no CI workflow
  and no hook invoking it — and the drain's current rule is that any printed finding blocks.
  Introducing advisories therefore requires changing that rule, which Story 4 owns; it is not a
  safe additive change.

Out of Scope

• Moving interaction prose off the page entirely (per-edge files, deleting the Integration
  Points section, retiring the reciprocity fan-out). Filed as a backlog stub; Story 1's successor
  trigger is what routes back to it.
• Enforcing splits earlier via a watermark and a create-bias re-curation. Filed as a backlog
  stub. It is page hygiene, not a fix for this problem — splitting a high-degree page increases
  total edge prose.
• Raising the 400-word number.
• The 7-invariant cap, which 22 of 47 pages sit on. A parallel symptom, separately triggered.
• Any change to touches: semantics, the no-topology line, or the atlas generator, which reads
  frontmatter and never the Integration Points prose.

Open Questions

None.

[sameera]

Close Record

Epic closed. Durable record below — the ephemeral close-record.md is hand-off only.

Decision record: #227 @ b86be99b2f25ee9fc8761c2baa86e813293db48e06f32ee0449f515696554058

Key Decisions

• The counted region is built by walking sections, not by slicing at a heading index. The
  pre-existing cap check sliced the body at the first ## Decision Log line and counted everything
  before it. Excluding a second section that way assumes an order the schema never fixes — a page may
  legally carry sections after Integration Points — so the shipped check walks the body line by line
  and drops every line inside an excluded section. Refuted alternative: keep the slice shape and slice
  twice, which is smaller but silently wrong for any page whose section order differs.

• Severity is an optional field whose absence means blocking. A finding carries
  severity: "advisory" or nothing at all, and one predicate reads absence as blocking. Every check
  that predates the two-severity output is blocking, so absence is the correct default and only a
  check that opts in has to say anything. Refuted alternative: a required two-valued severity on every
  finding — explicit at each call site, but it restates "blocking" at roughly forty existing push
  sites and makes a newly added blocking check fail to compile rather than behave correctly by
  default.

• The store-level revisit trigger is computed only on a full-store invocation. The two numbers are
  measured when the run scans the concepts directory itself and skipped when the caller passes an
  explicit file list. The drain invokes the validator with a changed-file list, so computing a
  store-wide sum there would add a full-store pass to every drain for a number that moves by fractions
  of a percent per drain and is acted on at review cadence. Refuted alternative: compute it on every
  run regardless of the file list.

• The stale claude-components pin inherited from main is corrected here rather than filed as its
  own bug. The re-vendor this epic already owed (record Invariant 14) rewrites the bundle
  fingerprint whole, so the inherited half could not be left stale without failing the same test this
  epic must leave green. Refuted alternative: re-pin only the validator entry by hand and file the
  drift separately — not available, because the vendor step writes the file whole and a hand-edit
  would be overwritten by the next run.

Deviation Rationale

• claude-components fingerprint re-pinned alongside validate-concepts.mjs (deviates from
  Decision Record: The Body Cap Measures the Concept, Not Its Neighbours #227's Invariant 14, which scoped the re-vendor to this epic's own tool change): the vendor step
  writes the bundle fingerprint whole, so the inherited stale claude-components hash could not be
  left alone without failing the same test this epic must leave green. Correcting it was the only
  available move, not an opportunistic one.

• The store-level revisit trigger shipped as executable code, where Story The schema states which words the cap counts #221's acceptance
  criteria required only that the contract state the trigger: Decision Record: The Body Cap Measures the Concept, Not Its Neighbours #227's revisit-trigger decision
  explicitly chose to have both numbers printed as a store-level advisory on a full-store run. The
  executable form is the record's decision, not scope the implementation invented; the story stated
  only the contract half of the same decision.

• Feature-space registration committed — the features index row and the Concept Store Capacity
  feature README — with no story acceptance criterion and no mention in Decision Record: The Body Cap Measures the Concept, Not Its Neighbours #227: planning hygiene implied
  by the epic's own feature_path, which pointed at a container that did not yet exist. Documentation
  only; no behaviour and no invariant touched.

None of the three contradicts a decision #227 made, so the record was not amended at close.

Pointers (durable)

• Deferred scope → Interaction Prose Moves Off the Concept Page #225 — Interaction Prose Moves Off the Concept Page (routed back to by the
  store-level revisit trigger stated in 0003 §2.2)
• Deferred scope → Concept Pages Split Before They Are Full #226 — Concept Pages Split Before They Are Full (watermark-driven splits and a
  create-bias re-curation)
• Process lesson → docs/delivery/lessons/2026-08-04-measure-before-fixing-thresholds.md

epic: "#220"
date: 2026-08-04
record: "#227"
record_hash: b86be99b2f25ee9fc8761c2baa86e813293db48e06f32ee0449f515696554058
analyze: clean
range:
  - repo: github.com/sameera/nexus
    base: 4871acc7a41593ae8ff3638819f4771c4fc4964d
    head: 278fd9e248d582fcc2b76f7eda124234799716e5