feat(systems): a System names its files — path patterns stored, validated and matched (milestone 444 step 3, #4756)

A System gains path_patterns: globs relative to the repo root (* within one
directory, ** across any depth, a plain directory covering everything under
it). One service validates them for every door, so the web UI and MCP refuse
the same bad pattern with the same message. systems_for_paths resolves paths
to every active System that covers them, which step 4 (#4757) uses to deliver
an area's rulings when its files are touched.

- schema: systems.path_patterns JSONB NOT NULL default [] (migration 0113)
- service: normalize_path_patterns, path_matches, systems_for_paths
- routes + MCP create_system/update_system accept it; [] clears
- web UI: a Files field in the create and edit forms, patterns on the card
- backup carries it through export and restore
- using-scribe reflex 7: tagging work keeps a System's files current

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/scribe/mcp/tools/systems.py

@@ -9,6 +9,7 @@ tools are thin wrappers.
 Sentinels (match the milestone/task tool conventions):
   - name="" / description="" / color="" / status="" → "leave unchanged" on update
   - order_index=-1 → "leave unchanged" on update (0 is a valid order_index)
+  - path_patterns=None → "leave unchanged" on update ([] clears them)
 """
 from __future__ import annotations
 
@@ -167,6 +168,7 @@ async def create_system(
     name: str,
     description: str = "",
     color: str = "",
+    path_patterns: list[str] | None = None,
 ) -> dict:
     """Create a System (a reusable, self-describing subsystem/area) in a project.
 
@@ -195,11 +197,20 @@ async def create_system(
     under the System, so a ruling there reaches each session working in the
     area; a quote in a work log reaches one only if a search matches it.
 
+    `path_patterns` name the files that ARE the area: globs relative to the
+    repo root, `*` within one directory, `**` across any depth, and a plain
+    directory covering everything under it (`src/billing`,
+    `frontend/src/components/Billing*.vue`). The description says what the
+    area is for; the patterns say where it lives, so work touching those files
+    can be traced to the System without a search. Give them when the area's
+    files are known; a System without them still works for tagging.
+
     Args:
         project_id: The project this system belongs to (required).
         name: Short label (required).
         description: What the system is and how it's used — a name is rarely enough.
         color: Optional UI accent (hex), or empty.
+        path_patterns: The area's files as repo-relative globs, or omit.
 
     Duplicate-gated like the other creates: if a System with the same
     normalized name already exists in this project (archived included), the
@@ -237,7 +248,7 @@ async def create_system(
     system = await systems_svc.create_system(
         uid, project_id=project_id, name=name,
         description=description or None, color=color or None,
-        canonical_id=applied,
+        canonical_id=applied, path_patterns=path_patterns,
     )
     if system is None:
         raise ValueError(f"cannot create system in project {project_id} (no write access)")
@@ -307,6 +318,7 @@ async def update_system(
     color: str = "",
     status: str = "",
     order_index: int = -1,
+    path_patterns: list[str] | None = None,
 ) -> dict:
     """Update a System. Only explicitly provided fields change.
 
@@ -319,10 +331,14 @@ async def update_system(
     history. If the charter above it contradicts a ruling, fix that sentence
     in the same edit.
 
+    `path_patterns` also REPLACES the whole list, and `[]` clears it.
+
     Args:
         status: 'active' or 'archived'. Archive a system to retire it without
             losing history; archived systems hide from default lists.
         order_index: display position (0-based); -1 = leave unchanged.
+        path_patterns: The area's files as repo-relative globs (see
+            create_system). Omit to leave unchanged; [] clears them.
     """
     uid = current_user_id()
     fields: dict = {}
@@ -336,6 +352,8 @@ async def update_system(
         fields["status"] = status
     if order_index >= 0:
         fields["order_index"] = order_index
+    if path_patterns is not None:
+        fields["path_patterns"] = path_patterns
     system = await systems_svc.update_system(uid, system_id, **fields)
     if system is None:
         raise ValueError(f"system {system_id} not found or no write access")

src/scribe/models/system.py

@@ -1,4 +1,5 @@
-from sqlalchemy import ForeignKey, Index, Integer, Text, UniqueConstraint
+from sqlalchemy import ForeignKey, Index, Integer, Text, UniqueConstraint, text
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column
 
 from scribe.models import Base
@@ -38,6 +39,15 @@ class System(Base, TimestampMixin, SoftDeleteMixin):
     # active | archived — systems accumulate; archive rather than delete.
     status: Mapped[str] = mapped_column(Text, default="active", server_default="active")
     order_index: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
+    # The files that ARE this area, as globs relative to the repo root
+    # (milestone 444). The description says what the area is FOR; these say
+    # where it lives, so a command or edit touching those files can be
+    # resolved to the System — and its rulings — without a similarity search.
+    # NOT NULL with a `[]` default for the reason DesignToken.supersedes gives:
+    # a nullable list has two empties, and every reader must handle both.
+    path_patterns: Mapped[list] = mapped_column(
+        JSONB, nullable=False, default=list, server_default=text("'[]'::jsonb")
+    )
 
     __table_args__ = (
         Index("ix_systems_project_id", "project_id"),
@@ -54,6 +64,7 @@ class System(Base, TimestampMixin, SoftDeleteMixin):
             "color": self.color,
             "status": self.status,
             "order_index": self.order_index,
+            "path_patterns": list(self.path_patterns or []),
             "created_at": iso(self.created_at),
             "updated_at": iso(self.updated_at),
         }

src/scribe/routes/systems.py

@@ -82,12 +82,16 @@ async def create_system_route(project_id: int):
     # Exact is mechanical and applied; overlap is a judgment call and is only
     # offered back for the form to present.
     applied = canonical["id"] if canonical and canonical["basis"] == "exact" else None
-    system = await systems_svc.create_system(
-        uid, project_id=project_id, name=data["name"],
-        description=data.get("description"), color=data.get("color"),
-        order_index=data.get("order_index", 0),
-        canonical_id=data.get("canonical_id") or applied,
-    )
+    try:
+        system = await systems_svc.create_system(
+            uid, project_id=project_id, name=data["name"],
+            description=data.get("description"), color=data.get("color"),
+            order_index=data.get("order_index", 0),
+            canonical_id=data.get("canonical_id") or applied,
+            path_patterns=data.get("path_patterns"),
+        )
+    except ValueError as e:
+        return jsonify({"error": str(e)}), 400
     if system is None:
         return jsonify({"error": "Permission denied"}), 403
     out = system.to_dict()
@@ -125,11 +129,14 @@ async def update_system_route(project_id: int, system_id: int):
     if system is None or system.project_id != project_id:
         return not_found("System")
     data = await request.get_json() or {}
-    allowed = {"name", "description", "color", "status", "order_index"}
+    allowed = {"name", "description", "color", "status", "order_index", "path_patterns"}
     fields = {k: v for k, v in data.items() if k in allowed}
     if "status" in fields and fields["status"] not in ("active", "archived"):
         return jsonify({"error": "status must be 'active' or 'archived'"}), 400
-    updated = await systems_svc.update_system(uid, system_id, **fields)
+    try:
+        updated = await systems_svc.update_system(uid, system_id, **fields)
+    except ValueError as e:
+        return jsonify({"error": str(e)}), 400
     if updated is None:
         return not_found("System")
     return jsonify(updated.to_dict())

src/scribe/services/backup.py

@@ -387,6 +387,7 @@ def _system_rows(rows, canonical_slugs: dict[int, str]) -> list[dict]:
             "id": r.id, "user_id": r.user_id, "project_id": r.project_id,
             "name": r.name, "description": r.description, "color": r.color,
             "status": r.status, "order_index": r.order_index,
+            "path_patterns": list(r.path_patterns or []),
             "canonical_slug": canonical_slugs.get(r.canonical_id or 0),
         }
         for r in rows
@@ -1460,6 +1461,8 @@ def _build_system(row: dict, maps: _Maps) -> System | None:
         color=row.get("color"),
         status=row.get("status", "active"),
         order_index=row.get("order_index", 0),
+        # Absent in a backup taken before milestone 444: no paths, not an error.
+        path_patterns=list(row.get("path_patterns") or []),
         # An unknown slug restores UNMAPPED rather than failing: the System and
         # its records are the payload, the mapping is an aid.
         canonical_id=maps.canonical_by_slug.get(row.get("canonical_slug") or ""),

src/scribe/services/systems.py

@@ -7,6 +7,7 @@ many-to-many through record_systems, mutable over time.
 """
 import logging
 from datetime import datetime, timezone
+from pathlib import PurePosixPath
 
 from sqlalchemy import delete, func, select
 
@@ -31,6 +32,87 @@ def local_name_key(name: str) -> str:
     return " ".join(name.split()).lower()
 
 
+# Bounds on what one System may claim. Generous for a real area — a handful of
+# directories and the odd stray file — and small enough that a pasted file
+# listing is refused rather than stored as the area's definition.
+MAX_PATH_PATTERNS = 50
+MAX_PATH_PATTERN_LENGTH = 300
+
+
+def normalize_repo_path(path: str) -> str:
+    """A path as the patterns see it: relative to the repo root, `/`-separated.
+
+    Shared by the patterns and the paths matched against them, so the two can
+    never disagree about whether `./src/x.py` and `src/x.py` are one file.
+    """
+    out = (path or "").strip().replace("\\", "/")
+    while out.startswith("./"):
+        out = out[2:]
+    out = out.lstrip("/")
+    while len(out) > 1 and out.endswith("/"):
+        out = out[:-1]
+    return out
+
+
+def normalize_path_patterns(patterns) -> list[str]:
+    """Validate and tidy a System's path patterns; ValueError says what is wrong.
+
+    Blank entries are dropped and repeats collapse, keeping the first-written
+    order. A pattern that climbs out of the repo (`..`) is refused rather than
+    dropped: it can never match, and storing it would read as coverage.
+    """
+    if patterns is None:
+        return []
+    if isinstance(patterns, str) or not isinstance(patterns, (list, tuple)):
+        raise ValueError("path_patterns must be a list of glob strings")
+    out: list[str] = []
+    for raw in patterns:
+        if not isinstance(raw, str):
+            raise ValueError("path_patterns must be a list of glob strings")
+        pattern = normalize_repo_path(raw)
+        if not pattern:
+            continue
+        if len(pattern) > MAX_PATH_PATTERN_LENGTH:
+            raise ValueError(
+                f"path pattern longer than {MAX_PATH_PATTERN_LENGTH} characters: "
+                f"{pattern[:60]}…"
+            )
+        if ".." in pattern.split("/"):
+            raise ValueError(
+                f"path pattern {pattern!r} leaves the repo — patterns are "
+                "relative to the repo root"
+            )
+        if pattern not in out:
+            out.append(pattern)
+    if len(out) > MAX_PATH_PATTERNS:
+        raise ValueError(
+            f"{len(out)} path patterns; a System takes at most "
+            f"{MAX_PATH_PATTERNS} — name directories with `**` rather than "
+            "listing their files"
+        )
+    return out
+
+
+def path_matches(pattern: str, path: str) -> bool:
+    """Whether a repo-relative path falls under one pattern.
+
+    Glob semantics are `PurePosixPath.full_match`: `*` stays inside one path
+    segment, `**` spans any number of them, and case counts. A pattern with
+    no wildcard that names a directory covers everything under it, so
+    `src/billing` means the directory the way a person writing it means it.
+    """
+    path = normalize_repo_path(path)
+    if not path or not pattern:
+        return False
+    candidate = PurePosixPath(path)
+    return candidate.full_match(pattern) or candidate.full_match(f"{pattern}/**")
+
+
+def matching_patterns(patterns, path: str) -> list[str]:
+    """The patterns among `patterns` that `path` falls under, in their order."""
+    return [p for p in (patterns or []) if path_matches(p, path)]
+
+
 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).
 
@@ -154,13 +236,18 @@ async def create_system(
     color: str | None = None,
     order_index: int = 0,
     canonical_id: int | None = None,
+    path_patterns: list[str] | None = None,
 ) -> System | None:
     """Create a System. None if the user can't write the project.
 
     `canonical_id` maps the new System onto the global catalog; leaving it None
     is fine — an unmapped System is fully usable, and the mapping can be
     proposed later (services/canonical_systems.propose_mappings).
+
+    `path_patterns` are validated here, so every door refuses the same bad
+    pattern with the same message (ValueError).
     """
+    patterns = normalize_path_patterns(path_patterns)
     if not await access.can_write_project(user_id, project_id):
         return None
     async with async_session() as session:
@@ -172,6 +259,7 @@ async def create_system(
             color=color,
             order_index=order_index,
             canonical_id=canonical_id,
+            path_patterns=patterns,
         )
         session.add(system)
         await session.commit()
@@ -209,13 +297,40 @@ async def list_systems(
         return list(result.scalars().all())
 
 
+async def systems_for_paths(
+    user_id: int, project_id: int, paths: list[str],
+) -> list[tuple[System, list[str]]]:
+    """The project's active Systems whose patterns cover any of `paths`.
+
+    Each comes with the paths it matched, in the order given. A path can match
+    several Systems — areas overlap, and every one it belongs to answers for
+    it — so nothing here picks a winner. Systems with no patterns never match:
+    an area that has not named its files is not claiming all of them.
+    """
+    wanted = [p for p in (normalize_repo_path(x) for x in paths or []) if p]
+    if not wanted:
+        return []
+    out: list[tuple[System, list[str]]] = []
+    for system in await list_systems(user_id, project_id):
+        patterns = system.path_patterns or []
+        if not patterns:
+            continue
+        hit = [p for p in wanted if matching_patterns(patterns, p)]
+        if hit:
+            out.append((system, hit))
+    return out
+
 async def update_system(user_id: int, system_id: int, **fields: object) -> System | None:
     """Update a System if the user can write its project."""
     # canonical_id is deliberately NOT settable here: canonical_systems.
     # set_system_canonical is its single writer, because it also validates the
     # catalog entry is live. Two entry points onto one column is the drift this
     # table exists to end.
-    allowed = {"name", "description", "color", "status", "order_index"}
+    allowed = {"name", "description", "color", "status", "order_index", "path_patterns"}
+    # Validated before anything is read, so a refused pattern changes nothing.
+    # `[]` is a value here, not "leave unchanged": it clears the paths.
+    if fields.get("path_patterns") is not None:
+        fields["path_patterns"] = normalize_path_patterns(fields["path_patterns"])
     async with async_session() as session:
         system = await session.get(System, system_id)
         if system is None or system.deleted_at is not None: