throughline 3.0.0__tar.gz → 3.2.0__tar.gz

{throughline-3.0.0/src/throughline.egg-info → throughline-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.0.0
+Version: 3.2.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' -->
-161
+164
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-26
+28
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21
@@ -178,6 +178,7 @@ tl docs [FILE ...] --check                     # CI gate: fail if any document i
 tl context                                    # agent-facing brief (IDD + this project's model)
 tl ratify <UID> --by <who>                    # a human takes accountability
 tl invalidate <UID> --reason "…"              # falsify; cascade suspect
+tl withdraw <UID> [<UID> …] --reason "…"      # a signature no longer stands; awaits a human again
 ```
 
 > `tl` and `throughline` are the same command — `tl` is the short alias, and
@@ -251,6 +252,10 @@ demo and the self-host graph are gated in CI and by the pre-commit hook.
   items: the two states that must never be signed off.
 - **invalidate** — falsify an assumption (or any node): it is rejected and every
   transitive dependent is marked `suspect` (its blast radius).
+- **withdraw** — set aside a signature that should no longer stand (wrong name,
+  signed off in error), one item or a batch. Content and dependents are untouched;
+  the item returns to awaiting a human, and who withdrew it, why, and whose
+  signature it was stay on record.
 
 ---
 

{throughline-3.0.0 → throughline-3.2.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' -->
-161
+164
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-26
+28
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21
@@ -150,6 +150,7 @@ tl docs [FILE ...] --check                     # CI gate: fail if any document i
 tl context                                    # agent-facing brief (IDD + this project's model)
 tl ratify <UID> --by <who>                    # a human takes accountability
 tl invalidate <UID> --reason "…"              # falsify; cascade suspect
+tl withdraw <UID> [<UID> …] --reason "…"      # a signature no longer stands; awaits a human again
 ```
 
 > `tl` and `throughline` are the same command — `tl` is the short alias, and
@@ -223,6 +224,10 @@ demo and the self-host graph are gated in CI and by the pre-commit hook.
   items: the two states that must never be signed off.
 - **invalidate** — falsify an assumption (or any node): it is rejected and every
   transitive dependent is marked `suspect` (its blast radius).
+- **withdraw** — set aside a signature that should no longer stand (wrong name,
+  signed off in error), one item or a batch. Content and dependents are untouched;
+  the item returns to awaiting a human, and who withdrew it, why, and whose
+  signature it was stay on record.
 
 ---
 

{throughline-3.0.0 → throughline-3.2.0}/pyproject.toml

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

@@ -10,6 +10,8 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
+import shutil
 import sys
 import time
 from pathlib import Path
@@ -24,11 +26,13 @@ from .grounding import (
     ratify,
     reaches_root,
     set_status,
+    withdraw,
 )
 from .identity import (
     RATIFICATION_ATTRS,
     RATIFIED_BY_ATTR,
     RATIFIED_ID_ATTR,
+    WITHDRAWN_RATIFIER_ATTR,
     IdentityError,
     default_ratifier,
 )
@@ -1355,6 +1359,7 @@ _CTX_COMMAND_USAGE = {
     "docs": "tl docs [FILE ...] [--at REF] [--check]",
     "status": "tl status <UID> <STATUS>",
     "invalidate": "tl invalidate <UID> [--reason …]",
+    "withdraw": "tl withdraw <UID> [<UID> …] --reason <why> --by <who>",
     "delete": "tl delete <UID>",
     "query": "tl query [--type T] [--status S] [--format json]",
     "register": "tl register new <PREFIX> <FOLDER> --title <…>",
@@ -1372,6 +1377,9 @@ _CTX_COMMAND_EMPHASIS = {
     "ratify": "a human accepts a proposed item; never run this for a human",
     "migrate": "idempotent repairs; extend this, never a script beside it",
     "invalidate": "retires an item and cascades suspicion — see grounding, below",
+    "withdraw": "removes a signature that should not stand (wrong name, signed in "
+                "error) without touching content or dependents; the item awaits a "
+                "human again — not `invalidate`, which says the item is false",
     "delete": "tombstones an item; the file stays, the item stops counting",
     "amend": "change content through the tool, never by opening the YAML",
     "schema": "change the schema itself — nouns: status, transition, type, attr, "
@@ -1794,7 +1802,8 @@ def cmd_ratify(args) -> int:
     # 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)
+    obstacle = ratification_obstacle(project.schema, idx, item,
+                                     replacing=args.replacing)
     if obstacle is not None:
         return _err(obstacle)
     # Ratifying is taking accountability, so the content comes before the signature
@@ -1823,8 +1832,12 @@ def cmd_ratify(args) -> int:
     # failure this guards, arriving by the back door.
     if change.stale:
         if interactive:
-            for line in render_change(change,
-                                      ratifier=item.attrs.get(RATIFIED_BY_ATTR)):
+            # Painted as git would paint it: colour on a terminal, none when the
+            # reader has asked for none (NO_COLOR, https://no-color.org).
+            for line in render_change(
+                    change, ratifier=item.attrs.get(RATIFIED_BY_ATTR),
+                    columns=shutil.get_terminal_size((80, 24)).columns,
+                    colour=not os.environ.get("NO_COLOR")):
                 print(line, file=sys.stderr)
             print("", file=sys.stderr)
         elif not args.accept_change:
@@ -1839,12 +1852,15 @@ def cmd_ratify(args) -> int:
     # 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}?"):
+    question = (f"replace the ratifier recorded on {uid} with {by}?"
+                if args.replacing else f"ratify {uid} as {by}?")
+    if interactive and not _confirm(question):
         print("not ratified", file=sys.stderr)
         return OK
     try:
         item = ratify(project, uid, by=by, index=idx,
-                      by_id=getattr(args, "by_id", None))
+                      by_id=getattr(args, "by_id", None),
+                      replacing=args.replacing)
     except IdentityError as e:
         return _err(str(e))
     except (ProjectError, GroundingError, SchemaError) as e:
@@ -1891,6 +1907,52 @@ def cmd_invalidate(args) -> int:
     return OK
 
 
+def cmd_withdraw(args) -> int:
+    """Withdraw the ratification of one or more items (SR-0197). The signature no
+    longer stands; the item goes back to awaiting a human; who withdrew it, why,
+    and whose signature it was are recorded. Content and dependents are untouched —
+    this is not ``invalidate``."""
+    try:
+        project = load_project(args.path)
+    except ProjectError as e:
+        return _err(str(e))
+    uids = list(args.uids)
+    if not uids:
+        # One item through the picker on a terminal; a batch is named explicitly.
+        uid = _resolve_uid(project, None, "withdraw the ratification of", "UID")
+        if uid is None:
+            return USAGE
+        uids = [uid]
+    # The reason is required, not optional: removing a signature is the quieter
+    # attack on an accountability record, and a withdrawal that says why is what
+    # makes it as accountable as the signature it removes. Asked once for the run.
+    reason = _resolve_value(args.reason, "reason", "--reason")
+    if reason is None:
+        return USAGE
+    by = _resolve_value(args.by, "withdrawer", "--by",
+                        default=default_ratifier(args.path))
+    if by is None:
+        return USAGE
+    # Confirmed on a terminal for the same reason ratify is (SR-0195): the act is
+    # about people, and a fully specified command is how a batch is run.
+    if _interactive() and not _confirm(
+            f"withdraw the ratification of {', '.join(uids)} as {by}?"):
+        print("not withdrawn", file=sys.stderr)
+        return OK
+    try:
+        items = withdraw(project, uids, by=by, reason=reason,
+                         by_id=getattr(args, "by_id", None))
+    except IdentityError as e:
+        return _err(str(e))
+    except (ProjectError, GroundingError, SchemaError) as e:
+        return _err(str(e))
+    for item in items:
+        write_item(item, project.register_of(item.uid))
+        print(f"{item.uid}: ratification by {item.attrs[WITHDRAWN_RATIFIER_ATTR]} "
+              f"withdrawn by {by}; now '{item.status}', awaiting ratification")
+    return OK
+
+
 def cmd_status(args) -> int:
     """The generic, transition-validated status verb (SR-0132). Every status
     move a project's [transitions] table permits is reachable through this
@@ -2281,6 +2343,12 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--accept-change", action="store_true",
                    help="accept a change made since the last ratification without "
                         "seeing it (non-interactive sessions only)")
+    # Correcting the identity on a record that was never published (SR-0196). Its
+    # own flag, because the act it permits — a signature over content that has not
+    # moved — is the one SR-0148 otherwise refuses outright.
+    s.add_argument("--replacing", action="store_true",
+                   help="replace the ratifier recorded on an uncommitted "
+                        "ratification, e.g. to correct a misspelled name")
     s.set_defaults(func=cmd_ratify)
 
     s = sub.add_parser("invalidate", help="falsify an item; cascade suspect")
@@ -2289,6 +2357,26 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--reason", default="")
     s.set_defaults(func=cmd_invalidate)
 
+    # Withdrawing a signature is its own verb, not a mode of ratify (SR-0197): it
+    # names no new accountable party and is the one act here anyone may perform,
+    # so it must not share a verb with the act that requires a named human.
+    s = sub.add_parser("withdraw",
+                       help="withdraw an item's ratification — the signature no "
+                            "longer stands; the item awaits a human again")
+    s.add_argument("uids", nargs="*", metavar="UID",
+                   help="item(s) whose ratification to withdraw (omit on a "
+                        "terminal to pick one)")
+    s.add_argument("--reason", default=None,
+                   help="why the signature should no longer stand (required; "
+                        "prompted for on a terminal)")
+    s.add_argument("--by", default=None,
+                   help="who is withdrawing it (omit on a terminal to be prompted; "
+                        "defaults to the identity this repository signs with)")
+    s.add_argument("--by-id", default=None, metavar="SCHEME:VALUE",
+                   help="optional stable identifier for the withdrawer, e.g. "
+                        "github:octocat or email:ada@example.com")
+    s.set_defaults(func=cmd_withdraw)
+
     s = sub.add_parser("status",
                        help="move an item to a status (transition-validated)")
     s.add_argument("uid", nargs="?", default=None,

{throughline-3.0.0 → throughline-3.2.0}/src/throughline/grounding.py

@@ -18,8 +18,13 @@ from typing import NamedTuple
 from .fingerprint import fingerprint
 from .graph import Index
 from .identity import (
+    RATIFICATION_ATTRS,
     RATIFIED_BY_ATTR,
     RATIFIED_ID_ATTR,
+    WITHDRAWN_BY_ATTR,
+    WITHDRAWN_ID_ATTR,
+    WITHDRAWN_RATIFIER_ATTR,
+    WITHDRAWN_REASON_ATTR,
     normalise_identifier,
 )
 from .model import Item, Link
@@ -67,7 +72,8 @@ def ratification_refusal(schema, idx: Index, item: Item) -> str | None:
     return None
 
 
-def ratification_obstacle(schema, idx: Index, item: Item) -> str | None:
+def ratification_obstacle(schema, idx: Index, item: Item, *,
+                          replacing: bool = False) -> 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).
@@ -88,14 +94,20 @@ def ratification_obstacle(schema, idx: Index, item: Item) -> str | None:
                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")
+        # A correction is the one signature over unchanged content that accepts
+        # something — the identity on the record (SR-0196). Whether it is allowed
+        # rests on the record being unpublished, which only :func:`ratify` can
+        # establish, so the refusal is lifted here and reimposed there.
+        if not replacing:
+            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; pass "
+                    "--replacing to correct the recorded ratifier instead")
     return None
 
 
 def ratify(project, uid: str, by: str, *, index: Index | None = None,
-           by_id: str | None = None) -> Item:
+           by_id: str | None = None, replacing: bool = False) -> Item:
     """A human takes accountability. Refused for ambiguous or ungrounded items —
     the two states that must not be signed off (scope-avalanche briefing §5).
 
@@ -118,9 +130,31 @@ def ratify(project, uid: str, by: str, *, index: Index | None = None,
     # 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)
+    obstacle = ratification_obstacle(schema, idx, item, replacing=replacing)
     if obstacle is not None:
         raise GroundingError(obstacle)
+    # A correction replaces the identity on a record that was never published
+    # (SR-0196). The test is made here rather than left to the caller, for the
+    # reason every other decision in this function is: a front end that could
+    # assert its way past it would be able to obtain a record this function would
+    # refuse to write. Unestablished is refused, not assumed — a correction is
+    # permitted on evidence the record was never shared, and absence of evidence
+    # is not that evidence.
+    superseded = None
+    if replacing:
+        from .ratification import SUPERSEDED_ATTR, ratification_is_committed
+        published = ratification_is_committed(project, item)
+        if published is None:
+            raise GroundingError(
+                f"{uid}: cannot establish whether this ratification has been "
+                "committed, so it may not be replaced — a correction is only "
+                "allowed for a record that was never published")
+        if published:
+            raise GroundingError(
+                f"{uid} was ratified by {item.attrs.get(RATIFIED_BY_ATTR)} in a "
+                "commit, so that record may not be replaced: a published "
+                "signature is not something one caller may take from another")
+        superseded = item.attrs.get(RATIFIED_BY_ATTR)
     current = fingerprint(item, schema)
     # Advancing is the default, and is transition-validated — an item that cannot
     # legally reach the ratified status is refused rather than moved illegally. A
@@ -137,6 +171,11 @@ def ratify(project, uid: str, by: str, *, index: Index | None = None,
     if identifier is not None:
         item.attrs[RATIFIED_ID_ATTR] = identifier
     item.attrs["ratified_fingerprint"] = current
+    # Kept so a correction never reads as the original record (SR-0148's condition
+    # that an accountability record never changes without the graph showing it).
+    if superseded is not None and superseded != by:
+        from .ratification import SUPERSEDED_ATTR
+        item.attrs[SUPERSEDED_ATTR] = superseded
     return item
 
 
@@ -208,6 +247,75 @@ def invalidate(project, uid: str, reason: str = "") -> Invalidation:
     return Invalidation(affected, marked, refused)
 
 
+def withdraw(project, uids, *, by: str, reason: str,
+             by_id: str | None = None) -> list[Item]:
+    """Withdraw the ratification of each item in ``uids`` (SR-0197): the signature
+    no longer stands, the item returns to those awaiting a human, and the record
+    says who withdrew it, why, and whose signature it was.
+
+    Not invalidation, and deliberately its opposite in effect: ``tl invalidate``
+    says an item is false and cascades suspicion into everything grounded on it
+    (SR-0035); this says nothing about the item. Its words have not moved, so
+    nothing resting on them has lost its footing — content is untouched and no
+    dependent is restatused. The item moves to the status bound to the suspect
+    role (SR-0131), which every live status may reach (SR-0175) and which already
+    means what this needs: a human must look again.
+
+    Anyone may withdraw, because withdrawal takes nothing — the item cannot count
+    as ratified again until a real human accepts it — but the act is recorded, not
+    silent: stripping a colleague's sign-off and leaving an item that merely looks
+    unratified would be the quieter attack on an accountability record.
+
+    All or nothing: every item is checked before any is written, so a mistyped UID
+    in a batch is a failure the caller sees, never a half-applied run. Refused for
+    an item that carries no ratification, for an empty reason, and for a status the
+    project's lifecycle will not let move to suspect.
+    """
+    if not by or not by.strip():
+        raise GroundingError("a withdrawal must name who is withdrawing it")
+    if not reason or not reason.strip():
+        raise GroundingError("a withdrawal must state its reason — pass --reason")
+    identifier = normalise_identifier(by_id)          # IdentityError if malformed
+    schema = project.schema
+    suspect = schema.status_role("suspect")
+    items: list[Item] = []
+    seen: set[str] = set()
+    for uid in uids:
+        if uid in seen:
+            raise GroundingError(f"{uid} is named more than once")
+        seen.add(uid)
+        item = project.get(uid)
+        if item is None:
+            raise GroundingError(f"{uid} does not exist")
+        if not item.attrs.get(RATIFIED_BY_ATTR):
+            raise GroundingError(f"{uid} carries no ratification to withdraw")
+        if not schema.allows_transition(item.status, suspect):
+            raise GroundingError(
+                f"{uid}: status change '{item.status}' -> '{suspect}' is not an "
+                "allowed transition, so its ratification cannot be withdrawn")
+        items.append(item)
+    # The record the ratifying verbs own is cleared, and only that record: the
+    # withdrawn identity moves into the withdrawal record rather than vanishing,
+    # so the graph still shows that a signature was taken and then set aside.
+    cleared = [name for name, owner in RATIFICATION_ATTRS.items()
+               if owner != "withdraw"]
+    for item in items:
+        ratifier = item.attrs[RATIFIED_BY_ATTR]
+        for name in cleared:
+            item.attrs.pop(name, None)
+        item.attrs[WITHDRAWN_RATIFIER_ATTR] = ratifier
+        item.attrs[WITHDRAWN_BY_ATTR] = by
+        if identifier is not None:
+            item.attrs[WITHDRAWN_ID_ATTR] = identifier
+        else:
+            item.attrs.pop(WITHDRAWN_ID_ATTR, None)
+        item.attrs[WITHDRAWN_REASON_ATTR] = reason
+        set_status(schema, item, suspect)
+        item.attrs.setdefault("suspect_reasons", []).append(
+            f"ratification by {ratifier} withdrawn by {by}: {reason}")
+    return items
+
+
 def scout_ingest(project, report: dict) -> dict:
     """Fold a scout report in. Scout PROPOSES; humans RATIFY.
 

{throughline-3.0.0 → throughline-3.2.0}/src/throughline/identity.py

@@ -29,6 +29,16 @@ from pathlib import Path
 RATIFIED_BY_ATTR = "ratified_by"
 RATIFIED_ID_ATTR = "ratified_id"
 
+# The withdrawal record (SR-0197): a signature that should no longer stand is
+# removed, and what replaces it says who removed it, why, and whose signature it
+# was. Held once — a later withdrawal overwrites an earlier one, as SR-0196 keeps
+# only the immediately preceding identity; the graph is plain text under version
+# control, so the succession is recoverable from history.
+WITHDRAWN_BY_ATTR = "withdrawn_by"
+WITHDRAWN_ID_ATTR = "withdrawn_id"
+WITHDRAWN_REASON_ATTR = "withdrawn_reason"
+WITHDRAWN_RATIFIER_ATTR = "withdrawn_ratifier"
+
 # The ratification record, and the one command entitled to write each part of it
 # (SR-0170). Any operation that sets attributes generally reaches these too unless
 # it is stopped, which would make correcting a title and signing a name nobody gave
@@ -49,6 +59,19 @@ RATIFICATION_ATTRS = {
     # a false difference — but a hand-written one would still be a claim about an
     # accountability record made by something other than the verb that owns it.
     "ratified_revision": "migrate",
+    # The identity a correction replaced (SR-0196). Ratify writes it, because a
+    # correction is itself a ratification; it is guarded like the rest of the
+    # record because a hand-written one would claim that a signature succeeded
+    # another when none did.
+    "ratified_supersedes": "ratify",
+    # Withdrawing a signature is as much a claim about people as giving one — who
+    # withdrew it, whose it was — so the record is guarded like the rest (SR-0197).
+    # Withdraw is also the verb that clears the fields above; a hand edit that
+    # removed a signature would leave nothing saying one was ever taken.
+    WITHDRAWN_BY_ATTR: "withdraw",
+    WITHDRAWN_ID_ATTR: "withdraw",
+    WITHDRAWN_REASON_ATTR: "withdraw",
+    WITHDRAWN_RATIFIER_ATTR: "withdraw",
 }
 
 # A scheme-qualified identifier: 'github:octocat', 'email:ada@example.com'. The