The corrections came within the hour. CJ, on his phone, looking at the /work/ drawer. The web-history cards had just merged: four new entries covering twelve years of development work, all general-named per the entity policy already in place.
The first correction: the supermarket card. “Supermarket E-Commerce Refresh” described a Medusa headless build. That Medusa build isn’t the supermarket site. It’s a separate project, still unshipped, going to a client soon. The actual supermarket work is a different engagement with a named brand. The right one stays unnamed for now. Out came the card.
Less than an hour later: Flash UI. CJ: “flash ui is ui gen.” The card had taken its name from the repo README. The README predated the product’s January rebrand. Spec 029-uigen-rebrand had been unambiguous: “the app is now called uigen.” The README hadn’t caught up. The card had read the README.
Two corrections, one phone session. Both caught within an hour of the cards going live.
What they share
Neither correction was about naming style alone. The supermarket card was correctly named: “Supermarket E-Commerce Refresh” is a general description, which is what the entity policy requires for work where the client isn’t named publicly. The Flash UI card used a specific name, but one that had been the correct specific name until January.
The shared failure is deeper. Both cards described a state that had been true (or close to true) and had since moved. Flash UI was the product’s name. The Medusa build was associated with supermarket-sector work. Both sat in a middle-ground between properly specific and properly general: specific enough to be wrong, not sourced carefully enough to catch the change.
The distinction matters because middle-ground descriptions fail silently. There’s no error state, no flag. The card sits in the catalogue looking correct until someone reads the source and notices the discrepancy. The Uigen card wasn’t broken in any structural sense; it just said the wrong name. The supermarket card wasn’t wrong about the sector or the technology; it just attributed the work to an engagement that hadn’t happened yet. Both looked fine on first read.
Two things are authoritative. A current brand name, because the spec anchors it: Uigen holds because spec 029 says so. And a general category name, because it doesn’t name a client. “Supermarket E-Commerce Refresh” can’t be made wrong by a client relationship changing. What isn’t authoritative: a product name sourced from a README that hasn’t been maintained since before a rebrand, or a project attribution that assumes a client relationship before it’s confirmed.
The entity policy
The prior coverage of the Flash UI-to-Uigen correction documented that case in isolation. The supermarket card adds the second data point that makes the full rule explicit.
A catalogue entry has two stable states.
Brand name. The product’s current official name, sourced from the spec. Uigen, because spec 029 says so. When the brand changes, the spec changes first; the card follows the spec, not the README.
General name. A category description that doesn’t name the client or depend on a specific product name. “Supermarket E-Commerce Refresh.” “Medusa Headless Commerce Build.” Stable because they don’t depend on a client relationship being confirmed or a brand name remaining current.
The middle-ground fails. A stale product name (Flash UI after January) sits between “current brand” and “general category.” A client attribution for work that hasn’t shipped to that client sits between “confirmed client work” and “general commerce build.” Both outlive the facts they rest on. Neither can be made stable without external verification the catalogue can’t automate.
The policy is a forced binary: brand name from spec, or general name with no client. No third option.
The README problem
The Flash UI case is the clearest example of why README sourcing produces middle-ground names. READMEs are written at a point in time and updated when the developer remembers, which is not reliably after every product decision. Specs are maintained as formal records. Spec 029-uigen-rebrand was written on the day of the rebrand decision to document it.
Sourcing a card’s name from the spec rather than the README is the mechanical enforcement of the brand-name side of the policy. If the spec says Uigen, the card says Uigen. The README might still say Flash UI six months from now; that’s the README’s problem, not the catalogue’s.
Out of scope: automated sync between spec files and catalogue entries. That’s a tooling problem for a later sprint. For now the constraint is human: update the card when the spec changes.
The attribution problem
The supermarket case is less obvious because the naming style was already correct: general. The failure was in what the card described, not how it described it.
A general-named card still has to describe real work. “Supermarket E-Commerce Refresh” is a valid general name for supermarket e-commerce work that shipped. It’s not valid for a Medusa project going to a similar client sometime soon. The general naming policy protects against stale client attribution. It doesn’t protect against describing the wrong project.
The conservative read: a card exists only when the work exists and is ready for the catalogue. Anticipated projects don’t get entries until they ship, even when clearly defined and nearly done. The Medusa project will get a card when it ships. The actual supermarket work will get a general-named card when attribution is cleared.
What the corrections produced
The Flash UI card is now the Uigen card. Sourced from spec 029.
The supermarket card doesn’t exist. When the actual supermarket work is ready for the catalogue, it gets a general name. When the Medusa project ships, it gets its own entry.
The four web-history cards that triggered all of this remain. All four were correctly general-named from the start. The corrections didn’t touch them. They sharpened the policy by showing what violates it.
The rule
Brand name or general name. For brand names, source from spec, not README. General names wait until the work exists. No middle state (stale product name, premature client attribution) survives contact with a real catalogue. The policy didn’t exist in this explicit form before the hour that produced two corrections. Two naming states, one sourcing rule for each, no middle. That’s the whole thing.
