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
+46 -22
View File
@@ -197,36 +197,60 @@ async def create_system(
normalized name already exists in this project (archived included), the
call returns {"duplicate": true, "existing_id": ...} instead of creating —
tag records to that one, or update_system it if its charter needs work.
Also mapped against the GLOBAL area catalog, so the same word means the
same thing in every project (milestone 307). A name that IS a catalog area
up to spelling ("CI and Release" vs "CI & Release") is mapped for you and
the response says so. A name that merely RESEMBLES one comes back with
`canonical_suggestion` — an offer, not a decision: apply it with
map_system_to_canonical if it really is that area, ignore it if this is a
project-specific area. Either way the System is created; the catalog never
blocks a name.
"""
uid = current_user_id()
norm = " ".join(name.split()).lower()
if norm:
try:
existing = await systems_svc.list_systems(
uid, project_id, include_archived=True
)
except Exception:
existing = []
for s in existing:
if " ".join(s.name.split()).lower() == norm:
return {
"duplicate": True,
"existing_id": s.id,
"message": (
f"System '{s.name}' (#{s.id}) already covers this area "
"in this project. Tag records to it with system_ids, "
"or update_system it if the charter needs revising — "
"a second System with the same name would split the "
"area's records across two piles."
),
}
assessment = await systems_svc.assess_system_name(uid, project_id, name)
duplicate = assessment["duplicate"]
if duplicate:
return {
"duplicate": True,
"existing_id": duplicate["id"],
"message": (
f"System '{duplicate['name']}' (#{duplicate['id']}) already "
"covers this area in this project. Tag records to it with "
"system_ids, or update_system it if the charter needs "
"revising — a second System with the same name would split "
"the area's records across two piles."
),
}
# An exact match is mechanical, so it is applied; an overlap is a judgment
# call, so it is only offered (see services/canonical_systems).
canonical = assessment["canonical"]
applied = canonical["id"] if canonical and canonical["basis"] == "exact" else None
system = await systems_svc.create_system(
uid, project_id=project_id, name=name,
description=description or None, color=color or None,
canonical_id=applied,
)
if system is None:
raise ValueError(f"cannot create system in project {project_id} (no write access)")
return system.to_dict()
out = system.to_dict()
if applied:
out["canonical_note"] = (
f"Mapped to the global area '{canonical['name']}' — the same "
"spelling-insensitive name. Your System keeps the name you gave it."
)
elif canonical:
out["canonical_suggestion"] = {
**canonical,
"message": (
f"The global catalog has '{canonical['name']}', which may be "
f"this same area. If it is, map_system_to_canonical("
f"{system.id}, {canonical['id']}) so records and rules about "
"this area line up across projects. If this area is specific "
"to this project, ignore it — unmapped is a valid state."
),
}
return out
async def list_systems(project_id: int, include_archived: bool = False) -> dict: