feat(systems): the catalog reaches the moment a name is minted, and gets a face (#3028, milestone 307 step 2)
CI & Build / Python lint (push) Successful in 4s
CI & Build / Plugin hooks (push) Successful in 14s
CI & Build / TypeScript typecheck (push) Successful in 48s
CI & Build / integration (push) Successful in 38s
CI & Build / Python tests (push) Failing after 57s
CI & Build / Build & push image (push) Skipped

Step 1 found the reason the standard names never held, and it is sharper than
"prose doesn't fire": the list WAS real and it WAS seeded — but only on the
inception path, for a project with zero Systems. Ad-hoc create_system never
consulted it, which is how Forge minted "CI and Release" and Portal minted
"CI & release" after the constant already existed. This wires the vocabulary to
the moment that mints a name.

- services/systems.assess_system_name: the local duplicate gate AND the
  catalog lookup, in ONE service function both doors call. The gate lived only
  in the MCP tool, which is exactly how the web UI shipped without a check the
  agent surface enforced (#2482). REST now answers 409 with the System that
  already covers the area.
- An `exact` catalog hit is APPLIED (mechanical — the names differ only in
  spelling). An `overlap` is only OFFERED, on both doors: applying a judgment
  call silently is how a cross-project rule surfaces in the wrong project.
- canonical_systems.best_overlap is the ONE scorer behind the create-time
  offer and the review sweep, so the two surfaces can never name different
  areas for one System. It also takes the catalog the caller already holds,
  so the review is not an N+1.

UI (folded in from step 1 — rule 27, that step shipped with no human surface):
- SystemsSection: a Shared area picker on create and edit, the area on each
  card, and a collapsed review of proposals that appears only when there is
  something to decide. `exact` and `overlap` never share a style — one is
  mechanical, the other is the reviewer's judgment, and presenting them alike
  is how a wrong mapping gets waved through.
- Settings → Admin → Areas: the catalog itself, showing each entry's slug,
  because the slug is what decides whether two names are the same area and a
  rename moves it.
- A picker rather than a live matcher: reproducing the slug rule in TypeScript
  would give this feature two matchers to keep in step — the exact drift the
  catalog exists to end. The server stays authoritative.

tests/helpers.fake_system gains canonical_id=None: an unnamed attribute is an
auto-MagicMock and therefore truthy, which is the trap that helper exists for
(note 2109) and a nullable FK walks straight into it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-26 12:58:30 -04:00
co-authored by Claude Opus 5
parent 879ef3053e
commit c58529718b
12 changed files with 855 additions and 49 deletions
+60
View File
@@ -19,6 +19,66 @@ from scribe.services import canonical_systems as canonical_systems_svc
logger = logging.getLogger(__name__)
def local_name_key(name: str) -> str:
"""The within-project uniqueness key: case and spacing, nothing else.
Deliberately weaker than `canonical_slug`. This one answers "is this the
same System I already have here", where the operator's own spelling is the
thing being compared; the canonical slug answers "is this the same AREA as
some other project's System", where spelling is exactly what must be
ignored.
"""
return " ".join(name.split()).lower()
async def assess_system_name(user_id: int, project_id: int, name: str) -> dict:
"""What BOTH doors must know before minting a System name (milestone 307).
Lived in the MCP tool alone until now, which is how the web UI shipped
without a gate the agent surface enforced (#2482). One service function, so
the two doors cannot answer the same question differently (rule 33).
Returns `{"duplicate": …|None, "canonical": …|None}`:
- `duplicate` — this project already has a System by that name. A hard stop
for the caller: a second one splits the area's records across two piles.
- `canonical` — the global catalog covers this area, with a `basis`.
`exact` is mechanical and safe to apply on the spot; `overlap` is a
judgment call and must be OFFERED, never applied. Neither ever blocks:
an unmatched name is a project-specific area, which is legitimate.
Fails open on both arms — a naming aid must never break a create.
"""
out: dict = {"duplicate": None, "canonical": None}
key = local_name_key(name)
if not key:
return out
try:
for existing in await list_systems(user_id, project_id, include_archived=True):
if local_name_key(existing.name) == key:
out["duplicate"] = {"id": existing.id, "name": existing.name}
return out
except Exception:
logger.debug("system name assessment: local scan failed", exc_info=True)
return out
try:
exact = await canonical_systems_svc.find_by_name(name)
if exact is not None:
out["canonical"] = {
"id": exact.id, "name": exact.name, "basis": "exact",
}
return out
# No exact hit: fall back to the same overlap scoring the review
# surface uses, so a create-time offer and a later proposal never
# disagree about which area a name resembles.
near = await canonical_systems_svc.best_overlap(name)
if near is not None:
out["canonical"] = near
except Exception:
logger.debug("system name assessment: catalog lookup failed", exc_info=True)
return out
async def standard_systems() -> list[tuple[str, str]]:
"""The standard cross-project vocabulary (#2798) as (name, charter) pairs.