throughline 2.2.1__tar.gz → 2.3.0__tar.gz

{throughline-2.2.1/src/throughline.egg-info → throughline-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.2.1
+Version: 2.3.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,10 +36,10 @@ 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' -->
-159
+161
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-25
+26
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

{throughline-2.2.1 → throughline-2.3.0}/README.md

@@ -8,10 +8,10 @@ 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' -->
-159
+161
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-25
+26
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

{throughline-2.2.1 → throughline-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "2.2.1"
+version = "2.3.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-2.2.1 → throughline-2.3.0}/src/throughline/cli.py

@@ -20,6 +20,7 @@ from .graph import Index
 from .grounding import (
     GroundingError,
     invalidate,
+    ratification_obstacle,
     ratify,
     reaches_root,
     set_status,
@@ -1695,6 +1696,75 @@ def cmd_subgraph(args) -> int:
     return OK
 
 
+def _render_for_ratification(project, item, *, emit) -> None:
+    """Put the item in front of the person about to sign it (SR-0195, UR-0029).
+
+    Not :func:`throughline.inject.render_item`: that renders Markdown for a
+    published document, and states every attribute alike. A ratifier is being asked
+    to judge, so this separates the normative attributes — the ones whose change
+    breaks the signature — from the rest, and names each grounding target so the
+    'why' reads as a sentence instead of a bare UID the reader has to go and look
+    up. Emitted on stderr like every other piece of guidance (SR-0120), leaving
+    stdout to the one line that says what was ratified.
+    """
+    schema = project.schema
+    emit("")
+    emit(f"{item.uid}  [{item.type}/{item.status}] {item.title}".rstrip())
+    for label, body in (("", item.text), ("rationale", item.rationale)):
+        if not body:
+            continue
+        emit("")
+        if label:
+            emit(f"{label}:")
+        for line in body.splitlines():
+            emit(f"  {line}" if line else "")
+    grounding = [ln for ln in (_ground_line(project, link, schema)
+                               for link in item.links) if ln]
+    emit("")
+    if grounding:
+        emit("grounded by:")
+        for line in grounding:
+            emit(f"  {line}")
+    else:
+        # A root needs no grounding and says so; anything else could not have got
+        # this far, since ratification_obstacle refuses an ungrounded item.
+        emit("grounded by: nothing — this is a root and justifies itself")
+    normative = [n for n in schema.normative_attrs(item.type) if n in item.attrs]
+    if normative:
+        emit("")
+        emit("normative attributes (a change here breaks this signature): "
+             + " · ".join(f"{n}={item.attrs[n]}" for n in normative))
+    emit("")
+
+
+def _ground_line(project, link, schema) -> str | None:
+    """One grounding link rendered with its target's title, or None for a link that
+    confers no grounding — those are context, not justification, and listing them
+    here would present a 'relates' neighbour as a reason the item exists."""
+    if link.type not in schema.ground_link_types:
+        return None
+    target = project.get(link.target)
+    if target is None:
+        return f"{link.type} {link.target}  (unresolved)"
+    return f"{link.type} {link.target}  [{target.type}/{target.status}] {target.title}".rstrip()
+
+
+def _confirm(question: str) -> bool:
+    """Ask a yes/no question on an interactive terminal, defaulting to no (SR-0195).
+
+    A confirmation is not a prompt for a value, so it has no flag behind it and
+    SR-0120's rule that a fully specified command is never prompted for one does
+    not reach it: the whole point is to stop a command that already says everything
+    it needs to say. Silence, EOF and anything unrecognised all decline — the
+    default must never be the irreversible answer.
+    """
+    try:
+        raw = input(f"{question} [y/N]: ").strip().lower()
+    except EOFError:
+        return False
+    return raw in ("y", "yes")
+
+
 def cmd_ratify(args) -> int:
     try:
         project = load_project(args.path)
@@ -1705,6 +1775,26 @@ def cmd_ratify(args) -> int:
     uid = _resolve_uid(project, args.uid, "ratify", "UID")
     if uid is None:
         return USAGE
+    item = project.get(uid)
+    if item is None:
+        return _err(f"{uid} does not exist")
+    # Refuse before rendering anything or asking anyone (SR-0195). The old order
+    # asked who was taking accountability and only then discovered that nothing
+    # could be signed, which taught that the prompt was a formality. The index is
+    # built once and handed to ratify, so the question asked here and the write
+    # below read the same graph.
+    idx = Index.build(project)
+    obstacle = ratification_obstacle(project.schema, idx, item)
+    if obstacle is not None:
+        return _err(obstacle)
+    # Ratifying is taking accountability, so the content comes before the signature
+    # (UR-0029) — and before the identity prompt, so the reader knows what they are
+    # being asked about while they are being asked. Non-interactive runs render
+    # nothing: there is no reader to serve, and output nobody reads is noise in CI.
+    interactive = _interactive()
+    if interactive:
+        _render_for_ratification(
+            project, item, emit=lambda line: print(line, file=sys.stderr))
     # Offer the identity this repository already signs commits with (SR-0156). It
     # is only ever a default: _resolve_value shows it and takes it on assent, and a
     # non-interactive session that names no ratifier is refused, not signed for.
@@ -1712,8 +1802,18 @@ def cmd_ratify(args) -> int:
                         default=default_ratifier(args.path))
     if by is None:
         return USAGE
+    # The stop that makes the rendering more than decoration, asked whether or not
+    # --by was supplied (SR-0195) — a fully specified command is exactly how a bulk
+    # or habitual ratification is run, and display without a stop is a warning that
+    # scrolled past. SR-0120 permits it: confirming an act is not prompting for a
+    # value. Declining writes nothing and is not an error; the user was asked and
+    # answered.
+    if interactive and not _confirm(f"ratify {uid} as {by}?"):
+        print("not ratified", file=sys.stderr)
+        return OK
     try:
-        item = ratify(project, uid, by=by, by_id=getattr(args, "by_id", None))
+        item = ratify(project, uid, by=by, index=idx,
+                      by_id=getattr(args, "by_id", None))
     except IdentityError as e:
         return _err(str(e))
     except (ProjectError, GroundingError, SchemaError) as e:

{throughline-2.2.1 → throughline-2.3.0}/src/throughline/grounding.py

@@ -67,6 +67,33 @@ def ratification_refusal(schema, idx: Index, item: Item) -> str | None:
     return None
 
 
+def ratification_obstacle(schema, idx: Index, item: Item) -> str | None:
+    """Why :func:`ratify` would refuse ``item`` as the graph now stands, or ``None``
+    when it would proceed — the whole precondition set, asked without writing
+    anything (SR-0195).
+
+    ratify must refuse an item it cannot accept *before* a front end renders it or
+    asks anyone to confirm it, so "may this be signed?" has to be answerable ahead
+    of the act. :func:`ratify` answers it through this same function rather than
+    repeating the conditions, so the refusal a user is shown early is by
+    construction the refusal the write would have raised. It is a superset of
+    :func:`ratification_refusal`, which stays the narrower "must never be signed"
+    predicate the migration repair binds against (SR-0152) — an unstamped record
+    is exactly what that repair exists to complete, so it must not be told that an
+    already-ratified item has nothing to accept."""
+    refusal = ratification_refusal(schema, idx, item)
+    if refusal is not None:
+        return refusal
+    already = (item.status == schema.status_role("ratified")
+               if schema.ratify_moves_status
+               else item.attrs.get(RATIFIED_BY_ATTR) is not None)
+    if already and item.attrs.get("ratified_fingerprint") == fingerprint(item, schema):
+        return (f"{item.uid} is already ratified by "
+                f"{item.attrs.get('ratified_by', 'a human')} and its content has "
+                "not changed since — there is nothing to accept")
+    return None
+
+
 def ratify(project, uid: str, by: str, *, index: Index | None = None,
            by_id: str | None = None) -> Item:
     """A human takes accountability. Refused for ambiguous or ungrounded items —
@@ -86,26 +113,15 @@ def ratify(project, uid: str, by: str, *, index: Index | None = None,
         raise GroundingError(f"{uid} does not exist")
     schema = project.schema
     idx = index if index is not None else Index.build(project)
-    refusal = ratification_refusal(schema, idx, item)
-    if refusal is not None:
-        raise GroundingError(refusal)
-    # Ratifying an already-ratified item whose content has not moved accepts
-    # nothing, and would replace the record of who accepted it leaving no trace
-    # that it changed (SR-0148). An item ratified before the stamp existed has
-    # none to compare against, so that first call is allowed through and stamps it.
+    # Every reason this may be refused, including that an already-ratified item
+    # whose content has not moved accepts nothing and would replace the record of
+    # who accepted it leaving no trace that it changed (SR-0148). An item ratified
+    # before the stamp existed has none to compare against, so that first call is
+    # allowed through and stamps it.
+    obstacle = ratification_obstacle(schema, idx, item)
+    if obstacle is not None:
+        raise GroundingError(obstacle)
     current = fingerprint(item, schema)
-    # "Already ratified" is read from whatever this project uses as the durable
-    # proof (SR-0172). Where ratification advances the item, that is the status, as
-    # it always has been. Where it does not, the status says nothing about sign-off
-    # and the record itself is the only honest witness.
-    already = (item.status == schema.status_role("ratified")
-               if schema.ratify_moves_status
-               else item.attrs.get(RATIFIED_BY_ATTR) is not None)
-    if already and item.attrs.get("ratified_fingerprint") == current:
-        raise GroundingError(
-            f"{uid} is already ratified by "
-            f"{item.attrs.get('ratified_by', 'a human')} and its content has not "
-            "changed since — there is nothing to accept")
     # Advancing is the default, and is transition-validated — an item that cannot
     # legally reach the ratified status is refused rather than moved illegally. A
     # project that binds the ratified role to a workflow state turns this off, and

{throughline-2.2.1 → throughline-2.3.0}/src/throughline/validate.py

@@ -42,6 +42,7 @@ _DEFAULT_SEVERITY = {
     "uid-grammar": ERROR, "uid-collision": ERROR, "prefix-collision": ERROR,
     "malformed-link": ERROR,
     "schema": ERROR, "unknown-key": ERROR, "empty-graph": ERROR,
+    "empty-registers": WARNING,
     "dangling-link": ERROR, "deleted-link-target": ERROR, "refines-cycle": ERROR,
     "namespace-unresolved": ERROR,
     "grounding-cycle": ERROR, "orphan": ERROR, "unserved-root": ERROR,
@@ -142,21 +143,25 @@ def validate(project, strict: bool = False,
             f"the route, or `tl schema transition allow {status} {suspect}` "
             "adds this one")
 
-    # A run that discovered nothing is not a sound graph (SR-0146). Items live only
-    # beneath a register manifest, so a project whose manifests are missing, misnamed
-    # or unmigrated loads zero items — and every rule below then passes vacuously,
-    # reporting "sound" while nothing at all was validated.
+    # A run that discovered nothing validated nothing. Two causes, two rules:
+    # no register manifest at all is a misconfiguration — manifests missing,
+    # misnamed or unmigrated — and every rule below would pass vacuously,
+    # reporting "sound" while nothing was validated, so it is an error
+    # (SR-0146). Registers that exist but hold no items are the state a graph
+    # is in between choosing its registers and authoring its first item, so
+    # that is a warning, which --strict still raises to an error (SR-0194).
     if next(project.items(), None) is None:
         if not project.registers:
-            why = ("no register was found beneath this project — items are only "
-                   "loaded from a folder holding a .register.yml manifest; run "
-                   "`tl register new` to create one, or `tl migrate` if this "
-                   "project predates the current format")
+            add("empty-graph", "", str(project.path),
+                "no items were discovered, so this check validated nothing: no "
+                "register was found beneath this project — items are only loaded "
+                "from a folder holding a .register.yml manifest; run `tl register "
+                "new` to create one, or `tl migrate` if this project predates the "
+                "current format")
         else:
-            why = ("its registers hold no items — run `tl new <PREFIX>` to author "
-                   "one")
-        add("empty-graph", "", str(project.path),
-            f"no items were discovered, so this check validated nothing: {why}")
+            add("empty-registers", "", str(project.path),
+                "no items were discovered, so this check validated nothing: its "
+                "registers hold no items yet — run `tl new <PREFIX>` to author one")
 
     # Malformed structure tolerated at load time (SR-0134): a link entry that is
     # not a mapping or is missing its target would once have crashed the loader

{throughline-2.2.1 → throughline-2.3.0/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.2.1
+Version: 2.3.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,10 +36,10 @@ 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' -->
-159
+161
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-25
+26
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

{throughline-2.2.1 → throughline-2.3.0}/tests/test_doctor.py

@@ -148,6 +148,7 @@ def test_a_cli_in_its_own_venv_is_inspected_not_skipped(tmp_path, monkeypatch):
     script = _fake_cli_venv(tmp_path, "pipx-tl")
     monkeypatch.setattr(doctor, "TOOLCHAIN", ("throughline",))
     monkeypatch.setattr(doctor, "CLI_FOR", {"throughline": "tl"})
+    monkeypatch.setattr(doctor, "_toolchain_clis", lambda: ["tl"])
     monkeypatch.setattr(doctor.shutil, "which", lambda _c: str(script))
     monkeypatch.setattr(Path, "is_file", lambda self: self.name == "pyproject.toml")
     monkeypatch.setattr(
@@ -163,11 +164,73 @@ def test_a_cli_in_its_own_venv_is_inspected_not_skipped(tmp_path, monkeypatch):
     assert "does NOT convert an existing venv" in result.remediation
 
 
+def test_a_published_plain_name_passes_when_a_suffixed_one_runs_the_tree(
+    tmp_path, monkeypatch
+):
+    """The deliberate two-install arrangement (UR-0021).
+
+    `tl` is the release, kept on the plain name so estate work is gated against a
+    published build; `tl-local` runs the working tree. Nothing is standing in for
+    anything, so the check must report which command runs which and pass — failing
+    here would ban the arrangement outright.
+    """
+    released = _fake_cli_venv(tmp_path, "pipx-tl")
+    local = _fake_cli_venv(tmp_path, "pipx-tl-local")
+    monkeypatch.setattr(doctor, "TOOLCHAIN", ("throughline",))
+    monkeypatch.setattr(doctor, "CLI_FOR", {"throughline": "tl"})
+    monkeypatch.setattr(doctor, "_toolchain_clis", lambda: ["tl", "tl-local"])
+    monkeypatch.setattr(
+        doctor.shutil,
+        "which",
+        lambda c: str(local) if c == "tl-local" else str(released),
+    )
+    monkeypatch.setattr(Path, "is_file", lambda self: self.name == "pyproject.toml")
+    monkeypatch.setattr(
+        doctor,
+        "_kinds_in",
+        lambda p: {"throughline": ["editable", str(doctor.REPO_ROOT)]}
+        if "pipx-tl-local" in str(p)
+        else {"throughline": ["published", "2.2.1"]},
+    )
+
+    result = doctor.check_cli_toolchain_chained()
+
+    assert result.ok, result.detail
+    assert "tl \u2192 throughline: published 2.2.1" in result.detail
+    assert "tl-local \u2192 throughline: editable" in result.detail
+
+
+def test_no_command_runs_the_tree_is_the_only_failure(tmp_path, monkeypatch):
+    """Both names published means the contributor's edits run nowhere — the failure
+    the check still exists to catch."""
+    released = _fake_cli_venv(tmp_path, "pipx-tl")
+    local = _fake_cli_venv(tmp_path, "pipx-tl-local")
+    monkeypatch.setattr(doctor, "TOOLCHAIN", ("throughline",))
+    monkeypatch.setattr(doctor, "CLI_FOR", {"throughline": "tl"})
+    monkeypatch.setattr(doctor, "_toolchain_clis", lambda: ["tl", "tl-local"])
+    monkeypatch.setattr(
+        doctor.shutil,
+        "which",
+        lambda c: str(local) if c == "tl-local" else str(released),
+    )
+    monkeypatch.setattr(Path, "is_file", lambda self: self.name == "pyproject.toml")
+    monkeypatch.setattr(
+        doctor, "_kinds_in", lambda _p: {"throughline": ["published", "2.2.1"]}
+    )
+
+    result = doctor.check_cli_toolchain_chained()
+
+    assert not result.ok
+    assert "No command on PATH runs your working tree" in result.remediation
+    assert "pipx --suffix" in result.remediation
+
+
 def test_the_current_environment_is_not_reported_twice(monkeypatch):
     """The in-process check already judges it; naming it again as a CLI environment
     would report one divergence as two."""
     monkeypatch.setattr(doctor, "TOOLCHAIN", ("throughline",))
     monkeypatch.setattr(doctor, "CLI_FOR", {"throughline": "tl"})
+    monkeypatch.setattr(doctor, "_toolchain_clis", lambda: ["tl"])
     monkeypatch.setattr(
         doctor.shutil, "which", lambda _c: str(Path(sys.prefix) / "bin" / "tl")
     )
@@ -179,6 +242,57 @@ def test_the_current_environment_is_not_reported_twice(monkeypatch):
     assert result.detail == "no separate CLI environments"
 
 
+def test_any_suffix_is_discovered_not_just_a_blessed_one(tmp_path, monkeypatch):
+    """Which suffix a second install uses is the contributor's choice.
+
+    Naming one here would publish a private convention as project policy and quietly
+    fail everyone who picked a different word, so the extra names are read off PATH.
+    A separator is required, or `tlsomething` would be mistaken for the toolchain.
+    """
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    for name in ("tl", "tl-wibble", "tl_dev", "tlsomething", "unrelated"):
+        (bindir / name).write_text("#!/bin/sh\n")
+    monkeypatch.setattr(doctor.os, "get_exec_path", lambda: [str(bindir)])
+
+    found = doctor._toolchain_clis()
+
+    assert "tl-wibble" in found, "an arbitrary suffix must be discovered"
+    assert "tl_dev" in found
+    assert "tlsomething" not in found, "a separator is required, not a bare prefix"
+    assert "unrelated" not in found
+
+
+def test_a_command_sharing_a_prefix_but_not_the_toolchain_is_ignored(
+    tmp_path, monkeypatch
+):
+    """Discovery is deliberately loose, so the environment has to be the filter —
+    otherwise an unrelated `tl-*` tool would be reported as toolchain divergence."""
+    ours = _fake_cli_venv(tmp_path, "pipx-tl")
+    stranger = _fake_cli_venv(tmp_path, "pipx-tl-unrelated")
+    monkeypatch.setattr(doctor, "TOOLCHAIN", ("throughline",))
+    monkeypatch.setattr(doctor, "CLI_FOR", {"throughline": "tl"})
+    monkeypatch.setattr(doctor, "_toolchain_clis", lambda: ["tl", "tl-unrelated"])
+    monkeypatch.setattr(
+        doctor.shutil,
+        "which",
+        lambda c: str(stranger) if c == "tl-unrelated" else str(ours),
+    )
+    monkeypatch.setattr(Path, "is_file", lambda self: self.name == "pyproject.toml")
+    monkeypatch.setattr(
+        doctor,
+        "_kinds_in",
+        lambda p: {"throughline": ["absent", ""]}
+        if "pipx-tl-unrelated" in str(p)
+        else {"throughline": ["editable", str(doctor.REPO_ROOT)]},
+    )
+
+    result = doctor.check_cli_toolchain_chained()
+
+    assert result.ok, result.detail
+    assert "tl-unrelated" not in result.detail
+
+
 def test_probe_mode_reports_this_interpreter_as_json(capsys):
     """The probe is how one implementation of the rule is run in another environment
     — so it must stay machine-readable and stdout-clean."""

{throughline-2.2.1 → throughline-2.3.0}/tests/test_engine.py

@@ -368,6 +368,26 @@ def test_empty_graph_fails_rather_than_passing_vacuously(tmp_path):
     assert _errors(findings)
     assert "register" in next(f.message for f in findings if f.rule == "empty-graph")
 
+def test_registers_with_no_items_warn_rather_than_fail(tmp_path):
+    """Registers laid down but nothing authored yet is a legitimate state, not a
+    misconfiguration (SR-0194): it warns, so `check` exits 0, and it fails only
+    under --strict, as every warning does. A project with no manifest at all is
+    still SR-0146's error, tested above."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", str(root), "init", "--name", "t", "--bare"]) == 0
+    assert _cli(["-C", str(root), "register", "new", "INT", "vision"]) == 0
+    p = load_project(str(root))
+    assert next(p.items(), None) is None
+    findings = validate(p, strict=False)
+    severities = {f.rule: f.severity for f in findings}
+    assert severities.get("empty-registers") == "warning"
+    assert "empty-graph" not in severities
+    assert not _errors(findings)
+    assert "tl new" in next(f.message for f in findings if f.rule == "empty-registers")
+    assert _errors(validate(p, strict=True))
+    assert _cli(["-C", str(root), "check", "--quiet"]) == 0
+    assert _cli(["-C", str(root), "check", "--strict", "--quiet"]) == 1
+
 def test_unknown_top_level_key_is_reported(tmp_path):
     """A key that is neither a core field nor `attrs` is read by nothing, so a
     misplaced one fails silently — most damagingly `origin`, which at the top level
@@ -2906,12 +2926,141 @@ def test_ratify_wizard_prompts_for_ratifier(tmp_path, monkeypatch):
                  "--title", "feat", "--status", "proposed", "--ground", "INT-0001",
                  "--no-interactive"]) == 0
     # single type after picking is 'requirement'; but INT-0001 is also live, so the
-    # type stage runs: [intent, requirement] -> pick requirement(#2), item #1, then by.
-    _make_tty(monkeypatch, ["2", "1", "henry"])
+    # type stage runs: [intent, requirement] -> pick requirement(#2), item #1, then
+    # by, then the SR-0195 confirmation.
+    _make_tty(monkeypatch, ["2", "1", "henry", "y"])
     assert _cli(["-C", str(root), "ratify"]) == 0
     assert load_project(root).get("FR-0001").attrs["ratified_by"] == "henry"
 
 
+# ------------------------------------ ratify shows what is being signed (SR-0195)
+
+def _ratifiable(tmp_path):
+    """A scaffold holding one grounded, proposed requirement with both text and a
+    rationale — the shape a ratifier is actually asked to judge."""
+    root = _scaffold(tmp_path)
+    assert _cli(["-C", str(root), "new", "FR", "--type", "requirement",
+                 "--title", "Widget cache expires", "--status", "proposed",
+                 "--text", "The Tool shall evict a cached widget after an hour.",
+                 "--ground", "INT-0001", "--no-interactive"]) == 0
+    assert _cli(["-C", str(root), "amend", "FR-0001",
+                 "--rationale", "Stale widgets were served for days."]) == 0
+    return root
+
+
+def _tty_marking_prompts(monkeypatch, answers):
+    """An interactive terminal whose every prompt leaves a marker in the stream the
+    rendering also writes to, so a test can assert that the content came first
+    rather than merely that both appeared."""
+    import throughline.cli as _climod
+    monkeypatch.setattr(_climod, "_interactive", lambda: True)
+    supply = iter(answers)
+
+    def _input(*_a, **_k):
+        print("<<asked>>", file=sys.stderr)
+        return next(supply)
+
+    monkeypatch.setattr("builtins.input", _input)
+
+
+def test_ratify_renders_the_item_before_it_asks_anything(tmp_path, monkeypatch, capsys):
+    """The content a signature is being taken for goes in front of the signer, and
+    before any prompt (SR-0195, UR-0029) — text, rationale and each grounding target
+    named, not left as a UID to go and look up."""
+    root = _ratifiable(tmp_path)
+    _tty_marking_prompts(monkeypatch, ["henry", "y"])
+    assert _cli(["-C", str(root), "ratify", "FR-0001"]) == 0
+    err = capsys.readouterr().err
+    for shown in ("Widget cache expires",
+                  "The Tool shall evict a cached widget after an hour.",
+                  "Stale widgets were served for days.",
+                  "derives_from INT-0001"):
+        assert shown in err, shown
+    assert "why" in err                      # the grounding target's own title
+    assert err.index("Stale widgets") < err.index("<<asked>>")
+
+
+def test_ratify_renders_and_confirms_even_when_by_was_supplied(tmp_path, monkeypatch,
+                                                               capsys):
+    """A fully specified command is exactly how a habitual ratification is run, so it
+    is the one that must not skip the content or the stop (SR-0195). SR-0120 permits
+    the prompt: confirming an act is not prompting for a value."""
+    root = _ratifiable(tmp_path)
+    _tty_marking_prompts(monkeypatch, ["y"])
+    assert _cli(["-C", str(root), "ratify", "FR-0001", "--by", "henry"]) == 0
+    err = capsys.readouterr().err
+    assert "The Tool shall evict a cached widget after an hour." in err
+    assert "<<asked>>" in err                # the confirmation still happened
+    assert load_project(root).get("FR-0001").attrs["ratified_by"] == "henry"
+
+
+def test_declining_the_confirmation_writes_no_record(tmp_path, monkeypatch):
+    """The stop is a real stop: a declined confirmation records nothing. It is not an
+    error either — the user was asked and answered (SR-0195)."""
+    root = _ratifiable(tmp_path)
+    _make_tty(monkeypatch, ["henry", "n"])
+    assert _cli(["-C", str(root), "ratify", "FR-0001"]) == 0
+    item = load_project(root).get("FR-0001")
+    assert "ratified_by" not in item.attrs
+    assert item.status == "proposed"
+
+
+def test_silence_declines_the_confirmation(tmp_path, monkeypatch):
+    """The default must never be the irreversible answer (SR-0195): an empty answer
+    declines rather than signing."""
+    root = _ratifiable(tmp_path)
+    _make_tty(monkeypatch, ["henry", ""])
+    assert _cli(["-C", str(root), "ratify", "FR-0001"]) == 0
+    assert "ratified_by" not in load_project(root).get("FR-0001").attrs
+
+
+def test_ratify_refuses_before_rendering_or_asking(tmp_path, monkeypatch, capsys):
+    """An item that cannot be signed is refused before anything is rendered and
+    before anyone is asked to name themselves (SR-0195). The old order asked who was
+    taking accountability and only then discovered nothing could be signed."""
+    root = _scaffold(tmp_path)
+    assert _cli(["-C", str(root), "new", "FR", "--type", "requirement",
+                 "--title", "ungrounded", "--status", "proposed",
+                 "--no-interactive"]) == 0
+    _tty_marking_prompts(monkeypatch, [])    # any prompt would raise StopIteration
+    assert _cli(["-C", str(root), "ratify", "FR-0001"]) == 2
+    err = capsys.readouterr().err
+    assert "not grounded to a root" in err
+    assert "<<asked>>" not in err            # nobody was asked
+    assert "ungrounded" not in err           # and the item was never rendered
+
+
+def test_an_already_ratified_item_is_refused_before_rendering(tmp_path, monkeypatch,
+                                                              capsys):
+    """The same ordering for the other refusal (SR-0195, SR-0148): rendering an item
+    and taking a signature, only to then say there was nothing to accept, is the bug
+    this ordering closes. ratify asks one precondition function, so the refusal shown
+    early is the refusal the write would have raised."""
+    root = _ratifiable(tmp_path)
+    assert _cli(["-C", str(root), "ratify", "FR-0001", "--by", "alice"]) == 0
+    capsys.readouterr()                      # discard the first, legitimate run
+    _tty_marking_prompts(monkeypatch, [])    # any prompt would raise StopIteration
+    assert _cli(["-C", str(root), "ratify", "FR-0001"]) == 2
+    err = capsys.readouterr().err
+    assert "already ratified by alice" in err
+    assert "<<asked>>" not in err
+    assert "Widget cache expires" not in err
+    assert load_project(root).get("FR-0001").attrs["ratified_by"] == "alice"
+
+
+def test_non_interactive_ratify_renders_nothing_and_confirms_nothing(tmp_path, capsys):
+    """Without a terminal there is no reader to serve and nothing that may block, so
+    neither the rendering nor the confirmation applies and SR-0120's automation
+    guarantee is untouched (SR-0195)."""
+    root = _ratifiable(tmp_path)
+    assert _cli(["-C", str(root), "ratify", "FR-0001", "--by", "henry"]) == 0
+    out = capsys.readouterr()
+    assert "The Tool shall evict a cached widget after an hour." not in out.err
+    assert "Stale widgets were served for days." not in out.err
+    assert "FR-0001 ratified by henry" in out.out
+    assert load_project(root).get("FR-0001").attrs["ratified_by"] == "henry"
+
+
 def test_register_new_refuses_duplicate_prefix(tmp_path):
     """A prefix owns a UID namespace and must be unique (SR-0101). `tl register
     new` refuses a prefix another register already declares, exits with a usage