throughline 3.6.2__tar.gz → 3.7.0__tar.gz

{throughline-3.6.2/src/throughline.egg-info → throughline-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.6.2
+Version: 3.7.0
 Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-174
+178
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 30

{throughline-3.6.2 → throughline-3.7.0}/README.md

@@ -8,7 +8,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-174
+178
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 30

{throughline-3.6.2 → throughline-3.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "3.6.2"
+version = "3.7.0"
 description = "A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check."
 readme = "README.md"
 requires-python = ">=3.11"

{throughline-3.6.2 → throughline-3.7.0}/src/throughline/cli.py

@@ -20,6 +20,7 @@ from pathlib import Path
 from .dump import build_dump
 from .fingerprint import fingerprint
 from .graph import Index
+from .links import LinkError, add_link, remove_link, retype_link
 from .grounding import (
     GroundingError,
     attribute_removal_refusal,
@@ -48,7 +49,8 @@ from .storage import (
     CONFIG_NAME,
     MANIFEST_NAME,
     ProjectError,
-    baseline_statuses,
+    baseline_note,
+    read_baseline,
     init_project,
     load_project,
     load_project_at_ref,
@@ -695,48 +697,23 @@ def cmd_link(args) -> int:
     ltype = _resolve_value(args.type, "link type", "--type", options=link_types)
     if ltype is None:
         return USAGE
-    stamp = fingerprint(dst, project.schema) if args.stamp else None
-    if getattr(args, "retype", False):
-        # Retype changes an existing edge in place rather than adding a parallel
-        # one (SR-0143), so the semantic-link review the tool is built for — e.g.
-        # narrowing a mitigates to a relates — needs no hand-editing.
-        existing = [ln for ln in src.links if ln.target == dst_uid]
-        if not existing:
-            return _err(f"no existing link {src_uid} -> {dst_uid} to retype "
-                        f"(drop --retype to add a new one)")
-        present_types = {ln.type for ln in existing}
-        if len(present_types) > 1:
-            return _err(f"multiple link types {src_uid} -> {dst_uid} "
-                        f"({', '.join(sorted(present_types))}); remove the "
-                        f"unwanted one with `tl unlink` first")
-        old_type = existing[0].type
-        for ln in existing:
-            ln.type = ltype
-            if args.stamp:
-                ln.stamp = stamp
-        write_item(src, project.register_of(src.uid))
-        print(f"retyped {src_uid} {dst_uid}: --{old_type}--> is now --{ltype}-->"
-              + (" (stamped)" if args.stamp else ""))
-        return OK
-    # The same edge twice is never wanted: with --stamp it is the re-confirm
-    # command SR-0034 promises, refreshing the stored fingerprint in place;
-    # without it there is nothing to add, and a parallel duplicate would hide
-    # a stale stamp behind a fresh one.
-    same = [ln for ln in src.links if ln.target == dst_uid and ln.type == ltype]
-    if same:
-        if not args.stamp:
-            return _err(f"{src_uid} --{ltype}--> {dst_uid} already exists "
-                        f"(add --stamp to refresh its stamp, or --retype to "
-                        f"change its type)")
-        for ln in same:
-            ln.stamp = stamp
-        write_item(src, project.register_of(src.uid))
+    try:
+        if getattr(args, "retype", False):
+            # Retype changes an existing edge in place rather than adding a parallel
+            # one (SR-0143), refused where it would leave the graph ungrounded
+            # (SR-0211).
+            old_type = retype_link(project, src_uid, dst_uid, ltype, stamp=args.stamp)
+            print(f"retyped {src_uid} {dst_uid}: --{old_type}--> is now --{ltype}-->"
+                  + (" (stamped)" if args.stamp else ""))
+            return OK
+        outcome = add_link(project, src_uid, dst_uid, ltype, stamp=args.stamp)
+    except LinkError as e:
+        return _err(str(e))
+    if outcome == "restamped":
         print(f"restamped {src_uid} --{ltype}--> {dst_uid}")
-        return OK
-    src.links.append(Link(target=dst_uid, type=ltype, stamp=stamp))
-    write_item(src, project.register_of(src.uid))
-    print(f"linked {src_uid} --{ltype}--> {dst_uid}"
-          + (" (stamped)" if stamp else ""))
+    else:
+        print(f"linked {src_uid} --{ltype}--> {dst_uid}"
+              + (" (stamped)" if args.stamp else ""))
     return OK
 
 
@@ -754,25 +731,13 @@ def cmd_unlink(args) -> int:
     dst_uid = _resolve_uid(project, args.dst, "unlink to (destination)", "DST")
     if dst_uid is None:
         return USAGE
-    src = project.get(src_uid)
-    if src is None:
-        return _err(f"source {src_uid} does not exist")
-
-    def _matches(ln) -> bool:
-        return ln.target == dst_uid and (args.type is None or ln.type == args.type)
-
-    matched = [ln for ln in src.links if _matches(ln)]
-    if not matched:
-        what = f" of type '{args.type}'" if args.type else ""
-        return _err(f"no link {src_uid} -> {dst_uid}{what} to remove")
-    present_types = {ln.type for ln in matched}
-    if args.type is None and len(present_types) > 1:
-        return _err(f"multiple link types {src_uid} -> {dst_uid} "
-                    f"({', '.join(sorted(present_types))}); pass --type to "
-                    f"choose which to remove")
-    src.links = [ln for ln in src.links if not _matches(ln)]
-    write_item(src, project.register_of(src.uid))
-    for ltype in sorted(present_types):
+    # Removing a link is refused where it would leave the graph ungrounded
+    # (SR-0211); the operation is shared with composing tools (SR-0212).
+    try:
+        removed = remove_link(project, src_uid, dst_uid, args.type)
+    except LinkError as e:
+        return _err(str(e))
+    for ltype in removed:
         print(f"unlinked {src_uid} --{ltype}--> {dst_uid}")
     return OK
 
@@ -1011,14 +976,23 @@ def cmd_check(args) -> int:
         project = load_project(args.path)
     except ProjectError as e:
         return _err(str(e))
-    baseline = None
-    if project.schema.transitions is not None and args.base:
-        baseline = baseline_statuses(project, args.base)
+    # The baseline serves transition legality (SR-0083) and tombstone permanence
+    # (SR-0093), so it is read whether or not transitions are declared. A host
+    # without git supplies it as a directory (SR-0210); where it cannot be read,
+    # the result says which rules did not run (SR-0209).
+    try:
+        baseline = read_baseline(project, ref=args.base,
+                                 base_dir=getattr(args, "base_dir", None))
+    except ProjectError as e:
+        return _err(str(e))
+    note = baseline_note(project.schema, baseline)
     published = referenced_uids(project)  # None unless [docs] paths configured
-    findings = validate(project, strict=args.strict, baseline=baseline,
+    findings = validate(project, strict=args.strict, baseline=baseline.statuses,
                         published=published)
     if args.format == "json":
         print(json.dumps([f.to_dict() for f in findings], indent=2))
+        if note:
+            print(note, file=sys.stderr)
         return FINDINGS if any(f.severity == ERROR for f in findings) else OK
 
     for f in sorted(findings, key=lambda x: (x.severity != ERROR, x.uid)):
@@ -1029,6 +1003,10 @@ def cmd_check(args) -> int:
     if not args.quiet:
         for line in _check_summary(project):
             print(line, file=sys.stderr)
+    # Not a finding, so neither the findings nor the exit status move; printed
+    # even when quiet, because it qualifies the result a quiet run still reports.
+    if note:
+        print(f"\n{note}", file=sys.stderr)
     tally = f"\n{errs} error(s), {warns} warning(s)"
     if not args.quiet and errs == 0:
         tally += "  — graph is sound" + (" (strict)" if args.strict else "")
@@ -1500,7 +1478,7 @@ _CTX_COMMAND_USAGE = {
              "[--unset K]",
     "link": "tl link <SRC> <DST> --type <kind>",
     "unlink": "tl unlink <SRC> <DST> [--type <kind>]",
-    "check": "tl check [--strict] [--format json]",
+    "check": "tl check [--strict] [--format json] [--base REF | --base-dir DIR]",
     "ratify": "tl ratify <UID> --by <who> [--by-id <scheme:value>]",
     "trace": "tl trace <UID> [--direction in|out]",
     "blast": "tl blast <UID>",
@@ -2442,6 +2420,9 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--base", default="HEAD", metavar="REF",
                    help="git ref for the status-transition baseline "
                         "(default HEAD; empty to disable)")
+    s.add_argument("--base-dir", default=None, metavar="DIR",
+                   help="read the baseline from DIR, a copy of the project as it "
+                        "stood, instead of from git (for a host without git)")
     s.add_argument("--format", choices=["text", "json"], default="text")
     s.add_argument("--quiet", "-q", action="store_true",
                    help="suppress the graph summary (findings + tally only)")

{throughline-3.6.2 → throughline-3.7.0}/src/throughline/graph.py

@@ -44,6 +44,21 @@ class Index:
                 idx.backward.setdefault(link.target, []).append((item.uid, link.type))
         return idx
 
+    def with_edges(self, uid: str, *, remove=(), add=()) -> "Index":
+        """This index with ``uid``'s outgoing edges changed, leaving this one as it
+        was. ``remove`` and ``add`` are ``(target, type)`` pairs; every occurrence of
+        a removed pair goes. It is how a link operation sees the graph after the
+        change it is about to make (SR-0211)."""
+        gone = set(remove)
+        forward = dict(self.forward)
+        backward = dict(self.backward)
+        forward[uid] = [e for e in self.forward.get(uid, []) if e not in gone] + list(add)
+        for target in {t for t, _k in gone} | {t for t, _k in add}:
+            kept = [(s, k) for s, k in self.backward.get(target, [])
+                    if not (s == uid and (target, k) in gone)]
+            backward[target] = kept + [(uid, k) for t, k in add if t == target]
+        return Index(items=self.items, forward=forward, backward=backward)
+
     def out_links(self, uid: str, types: set[str] | None = None) -> list[tuple[str, str]]:
         return [(t, k) for t, k in self.forward.get(uid, [])
                 if types is None or k in types]

{throughline-3.6.2 → throughline-3.7.0}/src/throughline/grounding.py

@@ -36,6 +36,45 @@ def reaches_root(idx: Index, schema, uid: str) -> bool:
     return idx.reaches(uid, schema.is_root, schema.ground_link_types)
 
 
+def grounding_gap(schema, idx: Index, item: Item) -> str | None:
+    """Why ``item`` is not grounded, in the words the gate's `orphan` finding uses,
+    or ``None`` when it is. A root is grounded by definition. Shared by the gate
+    and by the link operations, so a change is refused by exactly the rule that
+    would have reported it (SR-0211)."""
+    if schema.is_root(item):
+        return None
+    if not idx.out_links(item.uid, schema.ground_link_types):
+        return f"{item.type} has no grounding link — nothing justifies it"
+    if not reaches_root(idx, schema, item.uid):
+        return "grounding chain never reaches a root"
+    return None
+
+
+def is_unserved(schema, idx: Index, item: Item) -> bool:
+    """True when ``item`` is a delivery root that nothing grounds into, the
+    gate's `unserved-root` finding."""
+    return (item.type in schema.delivery_roots
+            and not idx.in_links(item.uid, schema.ground_link_types))
+
+
+def ungrounded_by(schema, items, before: Index, after: Index) -> tuple[list[str], list[str]]:
+    """The items a change from ``before`` to ``after`` would leave reaching no root,
+    and the delivery roots it would leave served by nothing (SR-0211). Measured as
+    a difference, so an item already ungrounded before the change is not blamed on
+    it and a graph red elsewhere does not block an unrelated change."""
+    orphaned: list[str] = []
+    unserved: list[str] = []
+    for item in items:
+        if item.is_deleted:
+            continue
+        if grounding_gap(schema, before, item) is None \
+                and grounding_gap(schema, after, item) is not None:
+            orphaned.append(item.uid)
+        if not is_unserved(schema, before, item) and is_unserved(schema, after, item):
+            unserved.append(item.uid)
+    return sorted(orphaned), sorted(unserved)
+
+
 # ------------------------------------------------------------------ operations
 
 class GroundingError(ValueError):

throughline-3.7.0/src/throughline/links.py

@@ -0,0 +1,151 @@
+# Copyright (c) 2026 Henry J Grech-Cini
+# SPDX-License-Identifier: Apache-2.0
+"""Adding, restamping, retyping and removing a link (SR-0143, SR-0211, SR-0212).
+
+These are the operations behind `tl link` and `tl unlink`, offered here so a tool
+that grounds over a wider graph than the one it writes, such as tl-compose over a
+union, performs them through the Tool rather than through a copy that falls behind.
+Such a tool passes a :class:`GroundingView`; everything else is the operation's own.
+"""
+from __future__ import annotations
+
+from typing import Callable, NamedTuple
+
+from .fingerprint import fingerprint
+from .graph import Index
+from .grounding import ungrounded_by
+from .model import Item, Link
+from .storage import write_item
+
+
+class LinkError(ValueError):
+    """A link operation refused, saying why. Nothing was written."""
+
+
+class GroundingView(NamedTuple):
+    """The graph a link operation judges against (SR-0212): a grounding index, and
+    how a target written on an item is found in it. Left out, it is the project's
+    own graph."""
+    index: Index
+    find: Callable[[str], Item | None]
+
+
+def own_view(project) -> GroundingView:
+    return GroundingView(Index.build(project), project.get)
+
+
+def _source(project, src_uid: str) -> Item:
+    src = project.get(src_uid)
+    if src is None:
+        raise LinkError(f"source {src_uid} does not exist")
+    return src
+
+
+def _target(view: GroundingView, target: str) -> Item:
+    dst = view.find(target)
+    if dst is None:
+        raise LinkError(f"target {target} does not exist")
+    return dst
+
+
+def _refuse_ungrounding(project, view: GroundingView, src_uid: str, change: str, *,
+                        remove, add=()) -> None:
+    """Refuse ``change`` when it would leave the graph ungrounded (SR-0211)."""
+    after = view.index.with_edges(src_uid, remove=remove, add=add)
+    orphaned, unserved = ungrounded_by(project.schema, list(project.items()),
+                                       view.index, after)
+    if not orphaned and not unserved:
+        return
+    harm = []
+    if orphaned:
+        harm.append(f"leave {', '.join(orphaned)} reaching no root")
+    if unserved:
+        harm.append(f"leave {', '.join(unserved)} served by nothing")
+    raise LinkError(f"{change} would {' and '.join(harm)} — nothing was changed; "
+                    "link the replacement first, then remove this one")
+
+
+def add_link(project, src_uid: str, target: str, link_type: str, *,
+             stamp: bool = False, view: GroundingView | None = None) -> str:
+    """Add ``src --link_type--> target``. Where that edge already exists, refresh
+    its stamp in place when ``stamp`` is asked for, and refuse otherwise, since a
+    parallel duplicate would hide a stale stamp behind a fresh one (SR-0034).
+    Returns ``"linked"`` or ``"restamped"``."""
+    view = view or own_view(project)
+    src = _source(project, src_uid)
+    dst = _target(view, target)
+    value = fingerprint(dst, project.schema) if stamp else None
+    same = [ln for ln in src.links if ln.target == target and ln.type == link_type]
+    if same:
+        if not stamp:
+            raise LinkError(f"{src_uid} --{link_type}--> {target} already exists "
+                            "(add --stamp to refresh its stamp, or --retype to "
+                            "change its type)")
+        for ln in same:
+            ln.stamp = value
+        write_item(src, project.register_of(src.uid))
+        return "restamped"
+    src.links.append(Link(target=target, type=link_type, stamp=value))
+    write_item(src, project.register_of(src.uid))
+    return "linked"
+
+
+def retype_link(project, src_uid: str, target: str, link_type: str, *,
+                stamp: bool = False, view: GroundingView | None = None) -> str:
+    """Change the type of the edge joining ``src`` to ``target`` in place
+    (SR-0143), refused where the new type would leave the graph ungrounded
+    (SR-0211). Returns the type it had."""
+    view = view or own_view(project)
+    src = _source(project, src_uid)
+    dst = _target(view, target)
+    existing = [ln for ln in src.links if ln.target == target]
+    if not existing:
+        raise LinkError(f"no existing link {src_uid} -> {target} to retype "
+                        "(drop --retype to add a new one)")
+    types = {ln.type for ln in existing}
+    if len(types) > 1:
+        raise LinkError(f"multiple link types {src_uid} -> {target} "
+                        f"({', '.join(sorted(types))}); remove the unwanted one "
+                        "with `tl unlink` first")
+    old = existing[0].type
+    _refuse_ungrounding(project, view, src_uid,
+                        f"retyping {src_uid} --{old}--> {target} to {link_type}",
+                        remove={(dst.uid, old)}, add=[(dst.uid, link_type)])
+    value = fingerprint(dst, project.schema) if stamp else None
+    for ln in existing:
+        ln.type = link_type
+        if stamp:
+            ln.stamp = value
+    write_item(src, project.register_of(src.uid))
+    return old
+
+
+def remove_link(project, src_uid: str, target: str, link_type: str | None = None, *,
+                view: GroundingView | None = None) -> list[str]:
+    """Remove the edge joining ``src`` to ``target`` (SR-0143), naming its type when
+    several join them, refused where the removal would leave the graph ungrounded
+    (SR-0211). Returns the types removed."""
+    view = view or own_view(project)
+    src = _source(project, src_uid)
+
+    def matches(ln) -> bool:
+        return ln.target == target and (link_type is None or ln.type == link_type)
+
+    matched = [ln for ln in src.links if matches(ln)]
+    if not matched:
+        what = f" of type '{link_type}'" if link_type else ""
+        raise LinkError(f"no link {src_uid} -> {target}{what} to remove")
+    types = sorted({ln.type for ln in matched})
+    if link_type is None and len(types) > 1:
+        raise LinkError(f"multiple link types {src_uid} -> {target} "
+                        f"({', '.join(types)}); pass --type to choose which to remove")
+    dst = view.find(target)
+    # A target the view cannot find grounds nothing, so removing a link to it can
+    # leave nothing ungrounded.
+    if dst is not None:
+        _refuse_ungrounding(project, view, src_uid,
+                            f"removing {src_uid} --{types[0]}--> {target}",
+                            remove={(dst.uid, k) for k in types})
+    src.links = [ln for ln in src.links if not matches(ln)]
+    write_item(src, project.register_of(src.uid))
+    return types

{throughline-3.6.2 → throughline-3.7.0}/src/throughline/storage.py

@@ -844,92 +844,182 @@ def read_project(path: str | Path) -> Project:
 
 # -------------------------------------------------------------- git baseline
 
-def baseline_statuses(project: Project, ref: str = "HEAD") -> dict[str, str] | None:
-    """Map ``uid -> status`` as each item stood at git ``ref`` — the snapshot the
-    working tree is measured against.
-
-    Two consumers read this: transition legality (SR-0083), which only looks up
-    items still present in the working tree, and tombstone permanence (SR-0093),
-    which needs items that existed at ``ref`` but are *gone* now — a UID whose
-    file was erased by a bad merge or a stray ``git rm``. So the map covers both
-    the current items' prior status and any file present at ``ref`` but absent
-    today.
-
-    Returns ``None`` — both checks then silently no-op — when the project is not
-    inside a git work tree or ``ref`` cannot be resolved. Items absent at ``ref``
-    (newly added) are simply omitted: creation is not a transition.
-    """
-    root = Path(project.path).resolve()
-    try:
-        top = subprocess.run(
-            ["git", "-C", str(root), "rev-parse", "--show-toplevel"],
-            capture_output=True, text=True, check=True).stdout.strip()
-    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
-        return None
-    top = Path(top)
+class Baseline(NamedTuple):
+    """The status each item had at the baseline check measures the working tree
+    against (SR-0083, SR-0093), or why it could not be read (SR-0209).
 
-    # Resolve the ref once: an unborn HEAD or a bad --base makes the whole
-    # baseline unavailable (inert) rather than "everything looks new".
-    if subprocess.run(["git", "-C", str(top), "rev-parse", "--verify", "--quiet",
-                       f"{ref}^{{commit}}"], capture_output=True).returncode != 0:
-        return None
+    ``statuses`` maps ``uid -> status`` and is ``None`` exactly when
+    ``unavailable`` says why. A baseline that was read but holds nothing, as in a
+    repository with no commits yet, is an empty map: every item is new."""
+    statuses: dict[str, str] | None
+    unavailable: str | None = None
 
-    out: dict[str, str] = {}
+
+class _GitTree:
+    """The project's files as they stood at a git revision, read through one
+    batched `git cat-file` rather than a process per file."""
+
+    def __init__(self, top: Path, ref: str, prefix: str):
+        self.top, self.ref, self.prefix = top, ref, prefix
+
+    def files(self) -> list[str]:
+        out = subprocess.run(
+            ["git", "-C", str(self.top), "ls-tree", "-r", "-z", "--name-only",
+             self.ref, "--", self.prefix or "."],
+            capture_output=True, check=True).stdout
+        names = [n.decode("utf-8", "surrogateescape") for n in out.split(b"\0") if n]
+        return [n[len(self.prefix):] for n in names if n.startswith(self.prefix)]
+
+    def read(self, rels: list[str]) -> dict[str, str]:
+        if not rels:
+            return {}
+        request = "".join(f"{self.ref}:{self.prefix}{rel}\n" for rel in rels)
+        out = subprocess.run(
+            ["git", "-C", str(self.top), "cat-file", "--batch"],
+            input=request.encode("utf-8", "surrogateescape"),
+            capture_output=True, check=True).stdout
+        found: dict[str, str] = {}
+        at = 0
+        for rel in rels:
+            nl = out.index(b"\n", at)
+            header = out[at:nl].decode("utf-8", "surrogateescape")
+            at = nl + 1
+            if header.endswith((" missing", " ambiguous")):
+                continue
+            _sha, kind, size = header.rsplit(" ", 2)
+            body = out[at:at + int(size)]
+            at += int(size) + 1
+            if kind == "blob":
+                found[rel] = body.decode("utf-8", "replace")
+        return found
+
+
+class _DirectoryTree:
+    """The project's files as they stood, supplied by a host as a directory laid
+    out as the working tree is (SR-0210)."""
+
+    def __init__(self, root: Path):
+        self.root = root
+
+    def files(self) -> list[str]:
+        return sorted(p.relative_to(self.root).as_posix()
+                      for p in self.root.rglob("*.yml") if p.is_file())
+
+    def read(self, rels: list[str]) -> dict[str, str]:
+        found: dict[str, str] = {}
+        for rel in rels:
+            path = self.root / rel
+            if path.is_file():
+                found[rel] = path.read_text(encoding="utf-8", errors="replace")
+        return found
+
+
+def _statuses_in(project: Project, tree) -> dict[str, str]:
+    """Map ``uid -> status`` from the project's files as ``tree`` holds them.
+
+    The one reading of a baseline, whichever source supplies the files. Two rules
+    consume it: transition legality (SR-0083), which looks up items still present,
+    and tombstone permanence (SR-0093), which needs items present at the baseline
+    but gone now, a UID whose file was erased by a bad merge or a stray `git rm`.
+    A current item's status is read from its own path first; a file at a path no
+    current item occupies is keyed by the UID it names, so an item moved between
+    registers keeps the status it had."""
+    root = Path(project.path).resolve()
+    present: dict[str, str] = {}
     for item in project.items():
         if item._path is None:
             continue
         try:
-            rel = item._path.resolve().relative_to(top)
+            present[item._path.resolve().relative_to(root).as_posix()] = item.uid
         except ValueError:
             continue
+    rels = [r for r in tree.files() if Path(r).name not in _ALL_MANIFEST_NAMES]
+    out: dict[str, str] = {}
+    absent: list[tuple[str, str]] = []
+    for rel, text in tree.read(rels).items():
         try:
-            blob = subprocess.run(
-                ["git", "-C", str(top), "show", f"{ref}:{rel.as_posix()}"],
-                capture_output=True, text=True, check=True).stdout
-        except (subprocess.CalledProcessError, FileNotFoundError, OSError):
-            continue  # not present at ref (new file) or bad ref for this path
-        data = _load_yaml(blob) or {}
+            data = _load_yaml(text) or {}
+        except yaml.YAMLError:
+            continue
+        if not isinstance(data, dict):
+            continue
         status = data.get("status")
-        if isinstance(status, str):
-            out[item.uid] = status
-
-    # Files that existed at `ref` but are gone from the working tree now. No
-    # current item carries their status, so a transition can't be measured — but
-    # a vanished tombstone must still reach the gate (SR-0093). Read their status
-    # straight from the tree.
-    present = {i._path.resolve() for i in project.items() if i._path is not None}
-    # Scope the scan to this project's own subtree: a project may be a
-    # subdirectory of a larger repo (e.g. examples/ alongside the self-host
-    # graph), and a tombstone in a *sibling* project must not be read as this
-    # project's erased record.
+        if not isinstance(status, str):
+            continue
+        if rel in present:
+            out[present[rel]] = status
+        elif isinstance(data.get("uid"), str):
+            absent.append((data["uid"], status))
+    for uid, status in absent:
+        out.setdefault(uid, status)
+    return out
+
+
+def read_baseline(project: Project, *, ref: str | None = "HEAD",
+                  base_dir: str | Path | None = None) -> Baseline:
+    """Read the baseline from ``base_dir``, a copy of the project as it stood
+    (SR-0210), or else from git revision ``ref``. A falsy ``ref`` means the caller
+    disabled the baseline. Where it cannot be read, the result says why rather than
+    passing for a baseline in which nothing moved (SR-0209).
+
+    Raises ``ProjectError`` when ``base_dir`` names no directory: a baseline the
+    caller supplied and mistyped fails the command, rather than reading as absent."""
+    if base_dir is not None:
+        root = Path(base_dir)
+        if not root.is_dir():
+            raise ProjectError(f"baseline directory {root} does not exist")
+        return Baseline(_statuses_in(project, _DirectoryTree(root.resolve())))
+    if not ref:
+        return Baseline(None, "the baseline was disabled")
+    root = Path(project.path).resolve()
     try:
-        proj_rel = root.relative_to(top)
-        prefix = "" if proj_rel == Path(".") else proj_rel.as_posix() + "/"
-    except ValueError:
-        prefix = ""
+        top = Path(subprocess.run(
+            ["git", "-C", str(root), "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, check=True).stdout.strip())
+    except subprocess.CalledProcessError:
+        return Baseline(None, "the project is not in a git work tree")
+    except (FileNotFoundError, OSError):
+        return Baseline(None, "git cannot be run")
     try:
-        tree = subprocess.run(
-            ["git", "-C", str(top), "ls-tree", "-r", "--name-only", ref,
-             "--", prefix or "."],
-            capture_output=True, text=True, check=True).stdout.splitlines()
-    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
-        tree = []
-    for rel in tree:
-        if not rel.endswith(".yml") or Path(rel).name == MANIFEST_NAME:
-            continue
-        if (top / rel).resolve() in present:
-            continue  # a current item — already handled above
+        if subprocess.run(["git", "-C", str(top), "rev-parse", "--verify", "--quiet",
+                           f"{ref}^{{commit}}"], capture_output=True).returncode != 0:
+            # With no commits at all there is nothing earlier to compare, so every
+            # item is new; otherwise the revision named really is missing.
+            commits = subprocess.run(["git", "-C", str(top), "rev-list", "-n", "1", "--all"],
+                                     capture_output=True, text=True).stdout.strip()
+            if not commits:
+                return Baseline({})
+            return Baseline(None, f"the revision '{ref}' cannot be resolved")
+        # Scope to this project's own subtree: a project may sit beside another in
+        # one repository, and a sibling's tombstone is not this project's record.
         try:
-            blob = subprocess.run(
-                ["git", "-C", str(top), "show", f"{ref}:{rel}"],
-                capture_output=True, text=True, check=True).stdout
-        except (subprocess.CalledProcessError, FileNotFoundError, OSError):
-            continue
-        data = _load_yaml(blob) or {}
-        uid, status = data.get("uid"), data.get("status")
-        if isinstance(uid, str) and isinstance(status, str):
-            out.setdefault(uid, status)
-    return out
+            proj_rel = root.relative_to(top)
+            prefix = "" if proj_rel == Path(".") else proj_rel.as_posix() + "/"
+        except ValueError:
+            prefix = ""
+        return Baseline(_statuses_in(project, _GitTree(top, ref, prefix)))
+    except (FileNotFoundError, OSError):
+        return Baseline(None, "git cannot be run")
+    except subprocess.CalledProcessError:
+        return Baseline(None, f"the revision '{ref}' cannot be read")
+
+
+def baseline_note(schema, baseline: Baseline) -> str | None:
+    """The line check prints beside its result when the baseline rules did not run
+    (SR-0209): which rules, and why. ``None`` when they ran. Transition legality is
+    named only where the project declares transitions, since without a table it
+    has nothing to check."""
+    if baseline.unavailable is None:
+        return None
+    rules = (["transition legality"] if schema.transitions is not None else [])
+    rules.append("tombstone permanence")
+    return f"not checked: {' and '.join(rules)} — {baseline.unavailable}"
+
+
+def baseline_statuses(project: Project, ref: str = "HEAD") -> dict[str, str] | None:
+    """``uid -> status`` at git ``ref``, or ``None`` where it cannot be read. Kept
+    for callers of earlier releases; :func:`read_baseline` also says why."""
+    return read_baseline(project, ref=ref).statuses
 
 
 def load_project_at_ref(path: str | Path, ref: str) -> tuple[Project, str]:

{throughline-3.6.2 → throughline-3.7.0}/src/throughline/validate.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from .fingerprint import fingerprint
 from .filters import FilterError, safe_eval
 from .graph import Index
-from .grounding import reaches_root
+from .grounding import grounding_gap, is_unserved
 from .identity import WITHDRAWN_BY_ATTR, WITHDRAWN_RATIFIER_ATTR, WITHDRAWN_REASON_ATTR
 from .schema import COVERAGE_NEEDS_RE, ERROR, OFF, WARNING
 from .storage import CONFIG_NAME, FORMAT_VERSION, STATUS_ROLES_MAJOR
@@ -272,17 +272,15 @@ def validate(project, strict: bool = False,
             elif target.is_deleted:
                 add("deleted-link-target", item.uid, f, f"link target '{link.target}' is deleted")
 
-        # Grounding coverage — the anti-avalanche core (upward).
-        if not schema.is_root(item):
-            if not idx.out_links(item.uid, ground_kinds):
-                add("orphan", item.uid, f,
-                    f"{item.type} has no grounding link — nothing justifies it")
-            elif not reaches_root(idx, schema, item.uid):
-                add("orphan", item.uid, f,
-                    "grounding chain never reaches a root")
+        # Grounding coverage — the anti-avalanche core (upward). The predicate is
+        # shared with the link operations, which refuse a change this would report
+        # (SR-0211).
+        gap = grounding_gap(schema, idx, item)
+        if gap is not None:
+            add("orphan", item.uid, f, gap)
 
         # Downward coverage — every delivery root must be served (mirror).
-        if item.type in schema.delivery_roots and not idx.in_links(item.uid, ground_kinds):
+        if is_unserved(schema, idx, item):
             add("unserved-root", item.uid, f,
                 f"{item.type} has nothing deriving from / mitigating it — unserved")
 

{throughline-3.6.2 → throughline-3.7.0/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.6.2
+Version: 3.7.0
 Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-174
+178
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 30

{throughline-3.6.2 → throughline-3.7.0}/src/throughline.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/throughline/graph.py
 src/throughline/grounding.py
 src/throughline/identity.py
 src/throughline/inject.py
+src/throughline/links.py
 src/throughline/model.py
 src/throughline/ratification.py
 src/throughline/schema.py
@@ -27,9 +28,11 @@ src/throughline.egg-info/entry_points.txt
 src/throughline.egg-info/requires.txt
 src/throughline.egg-info/top_level.txt
 tests/test_amend.py
+tests/test_baseline.py
 tests/test_doctor.py
 tests/test_engine.py
 tests/test_filters.py
+tests/test_link_guard.py
 tests/test_normative_by_type.py
 tests/test_ratification_change.py
 tests/test_ratification_withdrawal.py

throughline-3.7.0/tests/test_baseline.py

@@ -0,0 +1,163 @@
+# Copyright (c) 2026 Henry J Grech-Cini
+# SPDX-License-Identifier: Apache-2.0
+"""The baseline check measures the working tree against (SR-0083, SR-0093): read
+whether or not transitions are declared, from git or from a directory a host
+supplies (SR-0210), and never silently absent (SR-0209).
+
+Where git was missing, `tl check` printed an unqualified pass over two rules it
+had not run (issue #5), and a project declaring no transitions skipped tombstone
+permanence even inside git.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from throughline.cli import main as cli_main
+from throughline.storage import load_project, read_baseline
+
+
+def _cli(argv) -> int:
+    return cli_main([str(a) for a in argv])
+
+
+def _git(root: Path, *args: str) -> str:
+    return subprocess.run(["git", "-C", str(root), *args], capture_output=True,
+                          text=True, check=True).stdout
+
+
+def _commit(root: Path) -> None:
+    _git(root, "add", "-A")
+    _git(root, "commit", "-qm", "baseline")
+
+
+def _repo(root: Path, *, transitions: bool = True) -> Path:
+    assert _cli(["-C", root, "init", "--no-demo"]) == 0
+    if not transitions:
+        cfg = root / "throughline.toml"
+        text = re.sub(r"\n\[transitions\]\n(?:(?!\[).*\n)*", "\n",
+                      cfg.read_text(encoding="utf-8"))
+        cfg.write_text(text, encoding="utf-8")
+        assert load_project(root).schema.transitions is None
+    _git(root, "init", "-q")
+    _git(root, "config", "user.email", "t@t")
+    _git(root, "config", "user.name", "t")
+    assert _cli(["-C", root, "new", "INT", "--type", "intent", "--title", "Why",
+                 "--no-interactive"]) == 0
+    for title in ("Moved", "Retired"):
+        assert _cli(["-C", root, "new", "REQ", "--title", title, "--text", "t.",
+                     "--ground", "INT-0001", "--no-interactive"]) == 0
+    if transitions:
+        assert _cli(["-C", root, "status", "REQ-0001", "approved"]) == 0
+        assert _cli(["-C", root, "status", "REQ-0001", "implemented"]) == 0
+    assert _cli(["-C", root, "delete", "REQ-0002", "--reason", "gone"]) == 0
+    _commit(root)
+    return root
+
+
+def _drift(root: Path) -> None:
+    """An illegal status move and an erased tombstone, not yet committed."""
+    moved = root / "requirements" / "REQ-0001.yml"
+    moved.write_text(moved.read_text(encoding="utf-8").replace(
+        "status: implemented", "status: draft"), encoding="utf-8")
+    (root / "requirements" / "REQ-0002.yml").unlink()
+
+
+def _copy_without_git(src: Path, dst: Path) -> Path:
+    shutil.copytree(src, dst, ignore=shutil.ignore_patterns(".git"))
+    return dst
+
+
+@pytest.fixture
+def repo(tmp_path) -> Path:
+    return _repo(tmp_path / "repo")
+
+
+def test_git_baseline_runs_both_rules_and_says_nothing_more(repo, capsys):
+    _drift(repo)
+    assert _cli(["-C", repo, "check"]) == 1
+    out = capsys.readouterr()
+    assert "bad-transition" in out.out and "tombstone-deleted" in out.out
+    assert "not checked" not in out.err
+
+
+def test_outside_git_the_result_names_the_rules_that_did_not_run(repo, tmp_path, capsys):
+    work = _copy_without_git(repo, tmp_path / "work")
+    _drift(work)
+    rc = _cli(["-C", work, "check"])
+    out = capsys.readouterr()
+    assert "bad-transition" not in out.out and "tombstone-deleted" not in out.out
+    assert ("not checked: transition legality and tombstone permanence — "
+            "the project is not in a git work tree") in out.err
+    # Not a finding: the exit status is what the findings alone make it.
+    assert rc == _cli(["-C", work, "check", "--base", ""])
+
+
+def test_json_stays_a_list_of_findings_and_the_note_goes_to_stderr(repo, tmp_path, capsys):
+    work = _copy_without_git(repo, tmp_path / "work")
+    capsys.readouterr()
+    _cli(["-C", work, "check", "--format", "json"])
+    out = capsys.readouterr()
+    assert isinstance(json.loads(out.out), list)
+    assert "not checked:" in out.err
+
+
+def test_a_disabled_or_unresolvable_baseline_is_named(repo, capsys):
+    _cli(["-C", repo, "check", "--base", ""])
+    assert "the baseline was disabled" in capsys.readouterr().err
+    _cli(["-C", repo, "check", "--base", "no-such-ref"])
+    assert "the revision 'no-such-ref' cannot be resolved" in capsys.readouterr().err
+
+
+def test_a_repository_with_no_commits_is_a_baseline_where_everything_is_new(tmp_path, capsys):
+    root = tmp_path / "fresh"
+    assert _cli(["-C", root, "init", "--no-demo"]) == 0
+    _git(root, "init", "-q")
+    assert read_baseline(load_project(root)).statuses == {}
+    capsys.readouterr()
+    _cli(["-C", root, "check"])
+    assert "not checked" not in capsys.readouterr().err
+
+
+def test_a_baseline_directory_runs_both_rules_outside_git(repo, tmp_path, capsys):
+    at_base = _copy_without_git(repo, tmp_path / "at-base")
+    work = _copy_without_git(repo, tmp_path / "work")
+    _drift(work)
+    assert _cli(["-C", work, "check", "--base-dir", at_base]) == 1
+    out = capsys.readouterr()
+    assert "bad-transition" in out.out and "tombstone-deleted" in out.out
+    assert "not checked" not in out.err
+
+
+def test_a_baseline_directory_that_does_not_exist_fails_the_command(repo, tmp_path, capsys):
+    assert _cli(["-C", repo, "check", "--base-dir", tmp_path / "missing"]) == 2
+    assert "does not exist" in capsys.readouterr().err
+
+
+def test_git_and_a_directory_read_the_same_baseline(repo, tmp_path):
+    """One reading of a baseline, whichever source supplies the files."""
+    at_base = _copy_without_git(repo, tmp_path / "at-base")
+    _drift(repo)
+    project = load_project(repo)
+    from_git = read_baseline(project, ref="HEAD")
+    from_dir = read_baseline(project, base_dir=at_base)
+    assert from_git.statuses == from_dir.statuses
+    assert from_git.statuses == {"INT-0001": "draft", "REQ-0001": "implemented",
+                                 "REQ-0002": "deleted"}
+
+
+def test_tombstone_permanence_runs_without_a_transitions_table(tmp_path, capsys):
+    """SR-0093 sets no condition on transitions; the gate used to."""
+    root = _repo(tmp_path / "repo", transitions=False)
+    (root / "requirements" / "REQ-0002.yml").unlink()
+    assert _cli(["-C", root, "check"]) == 1
+    assert "tombstone-deleted" in capsys.readouterr().out
+    work = _copy_without_git(root, tmp_path / "work")
+    _cli(["-C", work, "check"])
+    assert ("not checked: tombstone permanence — the project is not in a git "
+            "work tree") in capsys.readouterr().err

throughline-3.7.0/tests/test_link_guard.py

@@ -0,0 +1,124 @@
+# Copyright (c) 2026 Henry J Grech-Cini
+# SPDX-License-Identifier: Apache-2.0
+"""Removing or retyping a link never leaves the graph ungrounded (SR-0211), and the
+link operations accept a wider graph to judge against (SR-0212).
+
+Removing an item's last grounding link used to succeed and leave `tl check` red
+(issue #3), and a composing tool kept its own copy of adding a link, which drifted.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from throughline.cli import main as cli_main
+from throughline.graph import Index
+from throughline.links import GroundingView, LinkError, add_link, remove_link
+from throughline.storage import load_project
+
+
+def _cli(argv) -> int:
+    return cli_main([str(a) for a in argv])
+
+
+@pytest.fixture
+def graph(tmp_path) -> Path:
+    """INT-0001 is served by REQ-0001 and REQ-0003; INT-0002 by REQ-0003 alone.
+    REQ-0002 is grounded only through REQ-0001."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", root, "init", "--no-demo"]) == 0
+    for title in ("One", "Two"):
+        assert _cli(["-C", root, "new", "INT", "--type", "intent", "--title", title,
+                     "--no-interactive"]) == 0
+    assert _cli(["-C", root, "new", "REQ", "--title", "R1", "--ground", "INT-0001",
+                 "--no-interactive"]) == 0
+    assert _cli(["-C", root, "new", "REQ", "--title", "R2", "--ground", "REQ-0001",
+                 "--no-interactive"]) == 0
+    assert _cli(["-C", root, "new", "REQ", "--title", "R3", "--ground", "INT-0001",
+                 "--no-interactive"]) == 0
+    assert _cli(["-C", root, "link", "REQ-0003", "INT-0002", "--type", "derives_from"]) == 0
+    return root
+
+
+def _bytes(root: Path, uid: str) -> bytes:
+    return next(root.rglob(f"{uid}.yml")).read_bytes()
+
+
+def test_removing_the_last_grounding_link_is_refused_naming_all_it_would_orphan(graph, capsys):
+    before = _bytes(graph, "REQ-0001")
+    assert _cli(["-C", graph, "unlink", "REQ-0001", "INT-0001"]) == 2
+    err = capsys.readouterr().err
+    assert "leave REQ-0001, REQ-0002 reaching no root" in err
+    assert "nothing was changed" in err
+    assert _bytes(graph, "REQ-0001") == before
+
+
+def test_leaving_a_delivery_root_unserved_is_refused(graph, capsys):
+    assert _cli(["-C", graph, "unlink", "REQ-0003", "INT-0002"]) == 2
+    err = capsys.readouterr().err
+    assert "leave INT-0002 served by nothing" in err
+    assert "reaching no root" not in err
+
+
+def test_linking_the_replacement_first_lets_the_old_link_go(graph):
+    assert _cli(["-C", graph, "link", "REQ-0001", "INT-0002", "--type", "derives_from"]) == 0
+    assert _cli(["-C", graph, "unlink", "REQ-0001", "INT-0001"]) == 0
+    assert not [l for l in load_project(graph).get("REQ-0001").links
+                if l.target == "INT-0001"]
+
+
+def test_retyping_the_last_grounding_link_to_one_that_grounds_nothing_is_refused(graph, capsys):
+    assert _cli(["-C", graph, "link", "REQ-0001", "INT-0001", "--type", "relates",
+                 "--retype"]) == 2
+    assert "reaching no root" in capsys.readouterr().err
+    assert _cli(["-C", graph, "link", "REQ-0001", "INT-0001", "--type", "implements",
+                 "--retype"]) == 0
+
+
+def test_a_link_that_grounds_nothing_is_always_removable(graph):
+    assert _cli(["-C", graph, "link", "REQ-0002", "INT-0002", "--type", "relates"]) == 0
+    assert _cli(["-C", graph, "unlink", "REQ-0002", "INT-0002"]) == 0
+
+
+def test_a_graph_red_elsewhere_does_not_block_an_unrelated_removal(graph):
+    assert _cli(["-C", graph, "new", "REQ", "--title", "orphan", "--no-interactive"]) == 0
+    assert _cli(["-C", graph, "link", "REQ-0002", "INT-0002", "--type", "relates"]) == 0
+    assert _cli(["-C", graph, "unlink", "REQ-0002", "INT-0002"]) == 0
+
+
+def test_a_wider_view_judges_the_removal(graph):
+    """What a composing tool passes: here the wider graph also grounds REQ-0001 in
+    INT-0002, so a removal refused over the project alone is allowed."""
+    project = load_project(graph)
+    with pytest.raises(LinkError):
+        remove_link(project, "REQ-0001", "INT-0001")
+    wider = Index.build(project).with_edges("REQ-0001", add=[("INT-0002", "derives_from")])
+    assert remove_link(project, "REQ-0001", "INT-0001",
+                       view=GroundingView(wider, project.get)) == ["derives_from"]
+
+
+def test_adding_through_a_view_restamps_in_place_rather_than_duplicating(graph, tmp_path):
+    """A target found only in the wider graph, as a borrowed clause is: a second
+    --stamp refreshes the edge instead of adding another."""
+    other = tmp_path / "source"
+    assert _cli(["-C", other, "init", "--no-demo"]) == 0
+    assert _cli(["-C", other, "new", "INT", "--type", "intent", "--title", "Borrowed",
+                 "--no-interactive"]) == 0
+    source = load_project(other)
+    project = load_project(graph)
+
+    def find(target: str):
+        return source.get(target.split(":", 1)[1]) if target.startswith("src:") \
+            else project.get(target)
+
+    view = GroundingView(Index.build(project), find)
+    assert add_link(project, "REQ-0003", "src:INT-0001", "relates", stamp=True,
+                    view=view) == "linked"
+    assert add_link(project, "REQ-0003", "src:INT-0001", "relates", stamp=True,
+                    view=view) == "restamped"
+    with pytest.raises(LinkError, match="already exists"):
+        add_link(project, "REQ-0003", "src:INT-0001", "relates", view=view)
+    edges = [l for l in load_project(graph).get("REQ-0003").links
+             if l.target == "src:INT-0001"]
+    assert len(edges) == 1 and edges[0].stamp