feat(ledger): the scoped bucket — by-construction one-offs are stamped by the sync, not judged by a person (#2869, milestone 294)

The 2026-08 audit left 77% of Scribe's ledger `exempt`, most of it a Vue
component's scoped <style> rules and <script setup> functions — one-offs by
construction (unreachable from any other file) that add nothing when judged
one by one and bury the rows a person should look at.

- coverage: Definition carries its line; scoped_definitions() names, per
  .vue file, every sym and every css rule inside <style scoped>; ArchiveShape
  carries the flag.
- sync: such rows are stamped status=scoped / classified_by=mechanical with
  the by-construction reason (history event recorded); un-stamped back to
  unclassified if a later tree makes them ordinary; a judgment overrides.
- The machine still sees them: proposer, derive grouping, divergence, hook
  evidence, canonical stamping and classify_shapes_by_rule's default all
  treat unclassified + scoped as the unjudged set (_MECHANICAL_TODO). Only
  the human todo (status=unclassified) and largest_gaps exclude them.
- accounting counts `scoped`; coverage line and the project card legend show
  it; SHAPE_STATUSES gains it (no DB CHECK on status — no migration).
- shape-accounting skill documents the bucket; plugin 0.1.37.

Operator decision on #2869 (2026-08-21): keep extracting everything, stamp
mechanically, keep `exempt` a human judgment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/scribe/services/coverage.py

@@ -107,6 +107,7 @@ class Definition(NamedTuple):
     signature: str
     body_sha: str
     body: str
+    line: int = -1   # 0-based line the definition starts on (#2869)
 
 
 def _definition_on(raw: str) -> tuple[str, str] | None:
@@ -186,11 +187,47 @@ def extract_definitions(text: str) -> list[Definition]:
         block = lines[i:end]
         out.append(Definition(
             kind, name, lines[i].strip()[:_SIGNATURE_CAP], _block_sha(block),
-            "\n".join(block),
+            "\n".join(block), i,
         ))
     return out
 
 
+# --- by-construction scope (#2869) -------------------------------------------
+#
+# A Vue single-file component's `<style scoped>` rules and its `<script setup>`
+# functions cannot be reached from any other file: they are one-offs by
+# construction, not by judgment. The sync stamps them `scoped` (mechanical) so
+# the human todo holds only shapes a person should look at, while the bodies
+# stay in play for the proposer, derive grouping and divergence — the five
+# auth views' identical rules were found exactly there. Unscoped `<style>` in
+# a .vue and every non-.vue file stay ordinary.
+_STYLE_OPEN_RE = re.compile(r"^\s*<style\b[^>]*\bscoped\b", re.IGNORECASE)
+_STYLE_CLOSE_RE = re.compile(r"^\s*</style\s*>", re.IGNORECASE)
+
+
+def scoped_definitions(path: str, text: str, defs: list[Definition]) -> set[tuple[str, str]]:
+    """The (kind, name) pairs among ``defs`` that are one-offs by
+    construction in this file: every sym in a .vue, and every css rule
+    that starts inside a `<style scoped>` block. Empty for other files."""
+    if not (path or "").lower().endswith(".vue"):
+        return set()
+    ranges: list[tuple[int, int]] = []
+    open_at: int | None = None
+    for i, ln in enumerate(text.splitlines()):
+        if open_at is None and _STYLE_OPEN_RE.match(ln):
+            open_at = i
+        elif open_at is not None and _STYLE_CLOSE_RE.match(ln):
+            ranges.append((open_at, i))
+            open_at = None
+    out: set[tuple[str, str]] = set()
+    for d in defs:
+        if d.kind == "sym":
+            out.add((d.kind, d.name))
+        elif any(a <= d.line <= b for a, b in ranges):
+            out.add((d.kind, d.name))
+    return out
+
+
 def extract_shapes(text: str) -> list[tuple[str, str]]:
     """Every (kind, name) this text DEFINES — kind is "css" or "sym".
 
@@ -220,6 +257,7 @@ class ArchiveShape(NamedTuple):
     signature: str
     body_sha: str
     body: str
+    scoped: bool = False   # one-off by construction (#2869)
 
 
 def shapes_from_archive(blob: bytes) -> list[tuple[str, str, str]]:
@@ -250,9 +288,14 @@ def definitions_from_archive(blob: bytes) -> list[ArchiveShape]:
                 text = handle.read().decode("utf-8")
             except UnicodeDecodeError:
                 continue
+            defs = extract_definitions(text)
+            scoped = scoped_definitions(path, text, defs)
             shapes.extend(
-                ArchiveShape(path, d.kind, d.name, d.signature, d.body_sha, d.body)
-                for d in extract_definitions(text)
+                ArchiveShape(
+                    path, d.kind, d.name, d.signature, d.body_sha, d.body,
+                    (d.kind, d.name) in scoped,
+                )
+                for d in defs
             )
     return shapes
 
@@ -414,7 +457,7 @@ async def compute_coverage(
     # repo that was unreachable today still has live rows, and they count.
     rows = await shape_ledger.live_rows(project_id)
     counts = {"canonical": 0, "instance": 0, "variant": 0, "exempt": 0,
-              "unclassified": 0}
+              "scoped": 0, "unclassified": 0}
     for row in rows:
         counts[row.status] = counts.get(row.status, 0) + 1
     by_repo: dict[str, dict[str, int]] = {}
@@ -571,7 +614,7 @@ def coverage_line(coverage: dict) -> str:
     counts = coverage.get("counts") or {}
     breakdown = " · ".join(
         f"{counts[k]} {k}"
-        for k in ("canonical", "instance", "variant", "exempt")
+        for k in ("canonical", "instance", "variant", "exempt", "scoped")
         if counts.get(k)
     )
     line = (

src/scribe/services/shape_ledger.py

@@ -65,6 +65,17 @@ def location_covers(loc_path: str, loc_symbol: str, path: str, name: str) -> boo
     return _path_touches(loc_path, path)
 
 
+# The rows the machine may still speak about: nobody's judgment stands on
+# them. `scoped` (#2869) is the sync's own by-construction stamp — the
+# proposer, derive grouping, divergence, hook evidence and sweeps treat it
+# like the todo; only the human todo (`unclassified`) excludes it.
+_MECHANICAL_TODO = ("unclassified", "scoped")
+_SCOPED_REASON = (
+    "by construction: a Vue component's scoped <style> rule / <script setup> "
+    "function — unreachable from any other file (stamped by the coverage sync)"
+)
+
+
 async def sync_repo_shapes(
     project_id: int,
     repo_key: str,
@@ -76,7 +87,9 @@ async def sync_repo_shapes(
 
     ``shapes`` are (path, kind, name) triples, or the richer ArchiveShape
     records (#2792) whose 4th/5th fields — signature, body_sha — refresh the
-    row's content fingerprint. ``seen_marker`` is the commit the archive was
+    row's content fingerprint, and whose 7th (#2869) says the shape is a
+    one-off by construction: such rows are stamped `scoped` (mechanical)
+    while unjudged, and un-stamped if a later tree makes them reachable. ``seen_marker`` is the commit the archive was
     read at when the forge can say, else the ref name — provenance sugar;
     the row timestamps carry the when.
     """
@@ -96,20 +109,32 @@ async def sync_repo_shapes(
             path, kind, name = shape[0], shape[1], shape[2]
             signature = shape[3] if len(shape) > 3 else ""
             body_sha = shape[4] if len(shape) > 4 else ""
+            scoped = bool(shape[6]) if len(shape) > 6 else False
             key = (path, name, kind)
             if key in seen:
                 continue
             seen.add(key)
             row = by_key.get(key)
             if row is None:
-                session.add(CodeShape(
+                row = CodeShape(
                     project_id=project_id, repo_key=repo_key,
                     path=path, symbol=name, kind=kind,
                     first_seen_commit=seen_marker, last_seen_commit=seen_marker,
                     signature=signature, body_sha=body_sha,
-                ))
+                )
+                if scoped:
+                    await _judge(session, row, status="scoped", snippet_id=None,
+                                 by="mechanical", reason=_SCOPED_REASON, at=now)
+                else:
+                    session.add(row)
                 continue
             row.last_seen_commit = seen_marker
+            if scoped and row.status == "unclassified":
+                await _judge(session, row, status="scoped", snippet_id=None,
+                             by="mechanical", reason=_SCOPED_REASON, at=now)
+            elif not scoped and row.status == "scoped":
+                await _judge(session, row, status="unclassified", snippet_id=None,
+                             by=None, reason=None, at=now)
             if signature:
                 row.signature = signature
             if body_sha and body_sha != row.body_sha:
@@ -214,7 +239,7 @@ async def mark_canonicals(
                 ),
                 None,
             )
-            if covering is not None and row.status == "unclassified":
+            if covering is not None and row.status in _MECHANICAL_TODO:
                 await _judge(session, row, status="canonical", snippet_id=covering,
                              by="mechanical", reason=None, at=now)
             elif (
@@ -402,8 +427,9 @@ async def classify_shapes_where(
 ) -> dict:
     """The sweep form of classify_shapes (#2868): one judgment applied to
     every live row under ``path`` whose symbol matches ``pattern`` (and
-    ``kind``). By default only `unclassified` rows are touched — a sweep
-    must never silently overwrite a judgment; ``include_judged`` opts in.
+    ``kind``). By default only unjudged rows are touched — `unclassified`
+    and the sync's mechanical `scoped` stamp — a sweep must never silently
+    overwrite a judgment; ``include_judged`` opts in.
     Same gates as the row form (status vocabulary, snippet target, reason
     for variant/exempt, write access); one transaction, so it applies whole
     or not at all. Returns the count and a sample of what it judged."""
@@ -431,7 +457,7 @@ async def classify_shapes_where(
     async with async_session() as session:
         conds = [CodeShape.project_id == project_id, CodeShape.vanished_at.is_(None)]
         if not include_judged:
-            conds.append(CodeShape.status == "unclassified")
+            conds.append(CodeShape.status.in_(_MECHANICAL_TODO))
         rows = (await session.execute(select(CodeShape).where(*conds))).scalars().all()
         for row in rows:
             if not rule_matches(row, path=path, pattern=pattern, kind=kind):
@@ -736,7 +762,7 @@ async def stamp_write_path_instances(
                 )
                 session.add(row)
                 by_key[(name, kind)] = row
-            elif not (row.status == "unclassified" or row.classified_by == "hook"):
+            elif not (row.status in _MECHANICAL_TODO or row.classified_by == "hook"):
                 continue  # a judgment — or the canon itself — stands
             await _judge(session, row, status="instance", snippet_id=sid, by="hook",
                          reason=why, at=now)
@@ -1066,7 +1092,7 @@ async def propose_for_repo(
                 select(CodeShape).where(
                     CodeShape.project_id == project_id,
                     CodeShape.repo_key == repo_key,
-                    CodeShape.status == "unclassified",
+                    CodeShape.status.in_(_MECHANICAL_TODO),
                     CodeShape.vanished_at.is_(None),
                 )
             )
@@ -1155,7 +1181,7 @@ async def apply_derive_groups(project_id: int) -> int:
             await session.execute(
                 select(CodeShape).where(
                     CodeShape.project_id == project_id,
-                    CodeShape.status == "unclassified",
+                    CodeShape.status.in_(_MECHANICAL_TODO),
                     CodeShape.vanished_at.is_(None),
                     CodeShape.proposed_snippet_id.is_(None),
                 )
@@ -1239,7 +1265,7 @@ async def confirm_proposals(
 
     conds = [
         CodeShape.project_id == project_id,
-        CodeShape.status == "unclassified",
+        CodeShape.status.in_(_MECHANICAL_TODO),
         CodeShape.vanished_at.is_(None),
         CodeShape.proposed_snippet_id.isnot(None),
     ]
@@ -1396,7 +1422,7 @@ async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
         for siblings in by_dir.values():
             dom = dominant_canon(siblings)
             for r in siblings:
-                if r.status != "unclassified":
+                if r.status not in _MECHANICAL_TODO:
                     continue
                 if r.diverges_from is not None:
                     flagged += 1
@@ -1413,7 +1439,7 @@ async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
 
 def divergence_summary(rows: Iterable[CodeShape], *, top: int = 10) -> dict:
     """Readout view: flagged shapes (newest first) and the recheck count."""
-    flagged = [r for r in rows if r.diverges_from is not None and r.status == "unclassified"]
+    flagged = [r for r in rows if r.diverges_from is not None and r.status in _MECHANICAL_TODO]
     flagged.sort(key=lambda r: (r.created_at or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
     recheck = sum(1 for r in rows if r.recheck_at is not None and r.vanished_at is None)
     return {