deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/reasoning.py

@@ -0,0 +1,2981 @@
+"""CLI subcommands for Reasoning section (spec §6.3).
+
+Every command here addresses a file by its WORKSPACE filename, the same way
+`deepcell query` / `cat` / `ls` do. The `claim` / `assumption` inspection
+groups used to take a local `--file` path instead, which made them unusable
+from MCP (no checkout) and collided with the root `-f/--format`; they now
+fetch the XML through the API and parse it in-process. `reasoning-diff` is
+the one exception and is local by nature — it compares a working-tree file
+against its own git HEAD.
+
+Implementation note: parsing is done directly with stdlib xml.etree.ElementTree
+rather than importing the full backend DeepCellDocument stack, which carries
+heavy optional dependencies (defusedxml, etc.) not installed in the CLI venv.
+The logic mirrors backend/src/core/document/queries.py (get_claims,
+get_arguments, get_supersedes_chain, get_assumption_impact) and
+backend/src/core/validation/reasoning_diff.py (compute_reasoning_diff).
+
+KNOWN DUPLICATION (Phase 4 / I5)
+================================
+This module re-implements ~300 lines of XML traversal that lives canonically in
+backend/src/core/document/queries.py and backend/src/core/validation/reasoning_diff.py.
+Phase 4 deliberately defers the full collapse — the JS-side SDK
+(@deepcell/spreadsheet-sdk) does not yet publish a Python-native helper, and
+adding the backend stack as a CLI dependency carries heavy optional deps
+(defusedxml, lxml, calc-engine) that double the install footprint.
+
+Migration plan once a thin shared helper exists:
+  1. Publish a small `deepcell_reasoning` python package (or factor a
+     dependency-light subset of `src.core.document.queries` that only needs
+     stdlib XML) that exposes get_claims / get_arguments / get_supersedes_chain
+     / get_assumption_impact and compute_reasoning_diff.
+  2. Replace the helpers in this file with calls into that package; keep the
+     click command wiring unchanged.
+  3. The pinning golden-file contract test in tests/test_reasoning_commands.py
+     will detect any text-output drift introduced by the swap.
+
+Until then, every change here MUST be mirrored in the canonical backend code
+(or vice versa). The Phase 4 codegen pipeline locks the *typed schema* shared
+between Python and TypeScript; the *traversal logic* still lives in two places.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import click
+
+from ._swapped_args import FileFirstCommand, FileFirstGroup
+from ._write_opts import FileFirstWriteCommand, WriteCommand, write_message
+
+from deepcell_cli.commands.query import _get_xml
+from deepcell_cli._findings import cited_rules_footer, provenance, rule_citation
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_info,
+    echo_success,
+    echo_validation,
+    echo_warning,
+    output,
+    print_plain,
+)
+
+
+# ---------------------------------------------------------------------------
+# File / stdin transport for free-text options
+# ---------------------------------------------------------------------------
+
+# Path type for every `--<option>-file` companion: `-` must pass validation
+# (allow_dash) so stdin transport works.
+_TEXT_FILE = click.Path(exists=True, dir_okay=False, allow_dash=True)
+
+
+def _resolve_text_option(
+    inline: str | None, file_path: str | None, option: str,
+    *, required: bool = False,
+) -> str | None:
+    """Resolve a free-text option that may arrive inline or from a file.
+
+    File / stdin ('-') transport exists because inline shell arguments mangle
+    dollar amounts: inside double quotes bash expands "$0" to the shell path
+    and "$35" to "5", which run 20260812-062931 showed corrupting stored
+    reasoning text while every deterministic check stayed green.
+    """
+    if inline is not None and file_path is not None:
+        raise click.UsageError(
+            f"--{option} and --{option}-file are mutually exclusive"
+        )
+    if file_path is not None:
+        if file_path == "-":
+            return sys.stdin.read().rstrip("\n")
+        with open(file_path, "r", encoding="utf-8") as handle:
+            return handle.read().rstrip("\n")
+    if required and inline is None:
+        raise click.UsageError(
+            f"one of --{option} or --{option}-file is required"
+        )
+    return inline
+
+
+def _check_single_stdin(*file_paths: str | None) -> None:
+    """Refuse two '-' file options on one invocation — stdin can only be
+    consumed once, so the second would silently receive empty text."""
+    if sum(1 for p in file_paths if p == "-") > 1:
+        raise click.UsageError(
+            "only one option may read stdin ('-') per invocation"
+        )
+
+
+def _text_file_help(noun: str, inline_option: str) -> str:
+    """Help text for a `--<option>-file` companion option."""
+    return (
+        f"File holding the {noun} text; '-' reads stdin. Prefer this over "
+        f"--{inline_option} for text containing '$' — inline shell arguments "
+        "mangle dollar amounts."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Lightweight local XML reader — mirrors DeepCellDocument query methods
+# ---------------------------------------------------------------------------
+
+
+def _attrib(el: ET.Element, name: str) -> str:
+    """Return attribute value, checking both 'name' and '@name' forms."""
+    return el.get(name) or el.get(f"@{name}") or ""
+
+
+def _body_text(el: ET.Element) -> str:
+    """Extract body text from a <Body> child element."""
+    body = el.find("Body")
+    if body is None:
+        return ""
+    return (body.text or "").strip()
+
+
+def _load_reasoning(xml: str, label: str) -> ET.Element | None:
+    """Parse XML text and return the <Reasoning> element, or None if absent."""
+    try:
+        root = ET.fromstring(xml)
+    except ET.ParseError as exc:
+        click.echo(f"error: cannot parse '{label}': {exc}", err=True)
+        sys.exit(2)
+    return root.find("Reasoning")
+
+
+def _get_claims(reasoning: ET.Element) -> list[ET.Element]:
+    return reasoning.findall("Claim")
+
+
+def _get_arguments(reasoning: ET.Element) -> list[ET.Element]:
+    return reasoning.findall("Argument")
+
+
+def _get_claim_by_id(reasoning: ET.Element, claim_id: str) -> ET.Element | None:
+    for c in _get_claims(reasoning):
+        if _attrib(c, "id") == claim_id:
+            return c
+    return None
+
+
+def _get_supersedes_chain(reasoning: ET.Element, claim_id: str) -> list[ET.Element]:
+    """Walk supersedes edges from claim_id back through history. Newest first."""
+    # Build supersedes map: from_id -> to_id
+    sup: dict[str, str] = {}
+    for a in _get_arguments(reasoning):
+        if _attrib(a, "rel") == "supersedes":
+            src = _attrib(a, "from")
+            dst = _attrib(a, "to")
+            if src:
+                sup[src] = dst
+
+    chain: list[ET.Element] = []
+    seen: set[str] = set()
+    cur = claim_id
+    while cur and cur not in seen:
+        seen.add(cur)
+        c = _get_claim_by_id(reasoning, cur)
+        if c is not None:
+            chain.append(c)
+        cur = sup.get(cur, "")
+    return chain
+
+
+def _get_assumption_impact(reasoning: ET.Element, assumption_id: str) -> list[ET.Element]:
+    """Return Claims that depend_on the given assumption_id."""
+    results: list[ET.Element] = []
+    for a in _get_arguments(reasoning):
+        if _attrib(a, "rel") == "depends_on" and _attrib(a, "to") == assumption_id:
+            src = _attrib(a, "from")
+            c = _get_claim_by_id(reasoning, src)
+            if c is not None:
+                results.append(c)
+    return results
+
+
+def _summary(el: ET.Element, max_len: int = 80) -> str:
+    text = _body_text(el)
+    return text[:max_len]
+
+
+def _require_reasoning(ctx: Ctx, filename: str) -> ET.Element:
+    """Fetch FILENAME from the workspace, return its <Reasoning>; exit if absent."""
+    reasoning = _load_reasoning(_get_xml(ctx, filename), filename)
+    if reasoning is None:
+        click.echo("(no Reasoning section in file)")
+        sys.exit(0)
+    return reasoning
+
+
+# ---------- claim group ----------
+
+
+@click.group(cls=FileFirstGroup)
+def claim() -> None:
+    """Inspect Claims in a workspace .deepcell file.
+
+    Read-only views of one Claim or one status: its supersedes history, its
+    variant/consensus pair, and the falsified list. Whole-graph views and
+    every write live under `deepcell reasoning`.
+    """
+
+
+@claim.command("history", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("claim_id")
+@pass_ctx
+def claim_history(ctx: Ctx, filename: str, claim_id: str) -> None:
+    """Walk the supersedes chain backwards from CLAIM_ID (newest first).
+
+    FILENAME is a file in the active workspace, as `deepcell ls` lists it.
+    """
+    reasoning = _require_reasoning(ctx, filename)
+    chain = _get_supersedes_chain(reasoning, claim_id)
+    if not chain:
+        click.echo(f"claim '{claim_id}' not found", err=True)
+        sys.exit(1)
+    for c in chain:
+        cid = _attrib(c, "id")
+        status = _attrib(c, "status") or "active"
+        click.echo(f"{cid}  [{status}]  {_summary(c)}")
+
+
+@claim.command("variant", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("claim_id")
+@pass_ctx
+def claim_variant(ctx: Ctx, filename: str, claim_id: str) -> None:
+    """Show your view of CLAIM_ID beside the consensus it is a variant of.
+
+    Follows the outgoing `variant_of` Argument from CLAIM_ID in FILENAME and
+    prints both sides. Prints only your view when there is no such edge.
+    """
+    reasoning = _require_reasoning(ctx, filename)
+    c = _get_claim_by_id(reasoning, claim_id)
+    if c is None:
+        click.echo(f"claim '{claim_id}' not found", err=True)
+        sys.exit(1)
+
+    consensus_id: str = ""
+    for a in _get_arguments(reasoning):
+        if _attrib(a, "from") == claim_id and _attrib(a, "rel") == "variant_of":
+            consensus_id = _attrib(a, "to")
+            break
+
+    click.echo(f"My view ({claim_id}): {_summary(c, 120)}")
+    if consensus_id:
+        cs = _get_claim_by_id(reasoning, consensus_id)
+        if cs is not None:
+            click.echo(f"Consensus ({consensus_id}): {_summary(cs, 120)}")
+        else:
+            click.echo(f"Consensus ({consensus_id}): <not found in document>")
+    else:
+        click.echo("(no variant_of edge from this claim)")
+
+
+@claim.command("falsified")
+@click.argument("filename")
+@pass_ctx
+def claim_falsified(ctx: Ctx, filename: str) -> None:
+    """List every Claim in FILENAME whose status is `falsified`.
+
+    There is no date filter: a <Claim> carries no timestamp, so when it was
+    falsified is not in the document. Use `deepcell log` / `deepcell diff` to
+    see when the status changed.
+    """
+    reasoning = _require_reasoning(ctx, filename)
+    found = False
+    for c in _get_claims(reasoning):
+        if _attrib(c, "status") == "falsified":
+            cid = _attrib(c, "id")
+            click.echo(f"{cid}  {_summary(c, 100)}")
+            found = True
+    if not found:
+        click.echo("(no falsified claims)")
+
+
+# ---------- assumption group ----------
+
+
+@click.group(cls=FileFirstGroup)
+def assumption() -> None:
+    """Inspect Assumptions in a workspace .deepcell file.
+
+    Assumptions are written with `deepcell reasoning add-assumption` /
+    `update-assumption`; this group only reads them back.
+    """
+
+
+@assumption.command("impact", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("assumption_id")
+@pass_ctx
+def assumption_impact(ctx: Ctx, filename: str, assumption_id: str) -> None:
+    """List Claims that depend_on ASSUMPTION_ID.
+
+    Answers "what breaks if this assumption is wrong" for one node. Errors
+    when ASSUMPTION_ID is not in FILENAME; prints nothing and exits 0 when it
+    exists but nothing depends on it. Continue through calculations,
+    backlinks, prose, and slides with `deepcell guide revise/premise-change`.
+    """
+    reasoning = _require_reasoning(ctx, filename)
+    # A typo'd id must error — silent-empty was indistinguishable from a real
+    # assumption with no dependents.
+    known_ids = {
+        node_id
+        for node in reasoning.iter()
+        if (node_id := _attrib(node, "id"))
+    }
+    if assumption_id not in known_ids:
+        raise click.ClickException(
+            f"Reasoning node '{assumption_id}' not found in {filename} "
+            f"({len(known_ids)} nodes)."
+        )
+    impact = _get_assumption_impact(reasoning, assumption_id)
+    if not impact:
+        # Empty output (exit 0) is intentional — the id exists, it just has
+        # no dependents.
+        return
+    for c in impact:
+        cid = _attrib(c, "id")
+        status = _attrib(c, "status") or "active"
+        click.echo(f"{cid}  [{status}]  {_summary(c)}")
+
+
+# ---------------------------------------------------------------------------
+# reasoning-diff — stdlib XML implementation (mirrors backend reasoning_diff.py)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _ChangedRef:
+    drift_kind: str  # "structural" | "snapshot" | "semantic" | "logical"
+    ref: str         # e.g. "value:GM_PCT@Q1/projected", "item:GM", "assumption:a1"
+
+
+@dataclass
+class _DiffEntry:
+    node_id: str
+    drift_kind: str
+    change_summary: str
+
+
+def _parse_xml_string(xml_text: str) -> ET.Element:
+    """Parse an XML string and return the root element."""
+    try:
+        return ET.fromstring(xml_text)
+    except ET.ParseError as exc:
+        click.echo(f"error: cannot parse XML: {exc}", err=True)
+        sys.exit(2)
+
+
+def _parse_custom_dims_attr_et(attr_value: str | None) -> dict[str, str]:
+    """Parse a customDimensions attribute string ("k:v;k:v") into a dict.
+
+    Mirrors backend/src/core/calculation/dimensions.py:parse_custom_dimensions_attr.
+    """
+    if not attr_value:
+        return {}
+    out: dict[str, str] = {}
+    for pair in attr_value.split(";"):
+        pair = pair.strip()
+        if ":" in pair:
+            k, v = pair.split(":", 1)
+            k = k.strip()
+            v = v.strip()
+            if k:
+                out[k] = v
+    return out
+
+
+def _canonical_dims_et(attr_value: str | None) -> str:
+    if not attr_value:
+        return ""
+    dims = _parse_custom_dims_attr_et(attr_value)
+    if not dims:
+        return ""
+    return ";".join(f"{k}={v}" for k, v in sorted(dims.items()))
+
+
+def _index_values_et(root: ET.Element) -> dict:
+    """Return {(item, ctx, status, scenario, dims): value_str} for all Values."""
+    out: dict[tuple, str] = {}
+    values_el = root.find("Values")
+    if values_el is None:
+        return out
+    # ItemGroup-wrapped form
+    for ig in values_el.findall("ItemGroup"):
+        item = ig.get("itemRef") or ""
+        status = ig.get("statusRef") or ""
+        group_scenario = ig.get("scenarioRef") or ""
+        group_dims_attr = ig.get("customDimensions")
+        for v in ig.findall("Value"):
+            ctx = v.get("contextRef") or ""
+            v_scen = v.get("scenarioRef")
+            scenario = v_scen if v_scen else group_scenario
+            v_dims_attr = v.get("customDimensions")
+            dims_attr = v_dims_attr if v_dims_attr else group_dims_attr
+            dims_canon = _canonical_dims_et(dims_attr)
+            txt = (v.text or "").strip()
+            if item and ctx:
+                out[(item, ctx, status, scenario, dims_canon)] = txt
+    # Flat form: <Value itemRef=... contextRef=... statusRef=...>
+    for v in values_el.findall("Value"):
+        item = v.get("itemRef") or ""
+        ctx = v.get("contextRef") or ""
+        status = v.get("statusRef") or ""
+        scenario = v.get("scenarioRef") or ""
+        dims_canon = _canonical_dims_et(v.get("customDimensions"))
+        txt = (v.text or "").strip()
+        if item and ctx:
+            out[(item, ctx, status, scenario, dims_canon)] = txt
+    return out
+
+
+_CALC_IGNORE_ATTRS_ET = frozenset({"description", "displayName"})
+_CALC_IGNORE_CHILDREN_ET = frozenset({"Label", "Notes", "Description"})
+
+
+def _index_calcs_et(root: ET.Element) -> dict:
+    """Return {calc_id: canonical_repr} for all Calculation nodes.
+
+    Drops reorder-only attrs / children; normalizes Formula whitespace.
+    """
+    out: dict[str, str] = {}
+    calc_defs = root.find("CalculationDefinitions")
+    if calc_defs is None:
+        return out
+    for c in calc_defs.findall("Calculation"):
+        cid = c.get("id") or ""
+        if not cid:
+            continue
+        attribs = sorted(
+            (k, v) for k, v in c.attrib.items() if k not in _CALC_IGNORE_ATTRS_ET
+        )
+        # child elements
+        child_parts: list[str] = []
+        formulas = c.findall("Formula")
+        for f in formulas:
+            txt = (f.text or "")
+            child_parts.append("Formula=" + " ".join(txt.split()))
+        other_children: list[str] = []
+        for child in c:
+            if child.tag in _CALC_IGNORE_CHILDREN_ET or child.tag == "Formula":
+                continue
+            other_children.append(f"{child.tag}={ET.tostring(child, encoding='unicode').strip()}")
+        other_children.sort()
+        out[cid] = repr(attribs) + "|" + "|".join(child_parts + other_children)
+    return out
+
+
+def _index_items_et(root: ET.Element) -> set:
+    """Return the set of all itemId values defined in ItemDefinitions."""
+    item_defs = root.find("ItemDefinitions")
+    if item_defs is None:
+        return set()
+    return {el.get("itemId") for el in item_defs.findall("Item") if el.get("itemId")}
+
+
+def _index_item_signatures_et(root: ET.Element) -> dict[str, tuple[str, str]]:
+    """Return {itemId: (displayName, parentItemRef)} for rename heuristic."""
+    out: dict[str, tuple[str, str]] = {}
+    item_defs = root.find("ItemDefinitions")
+    if item_defs is None:
+        return out
+    for it in item_defs.findall("Item"):
+        iid = it.get("itemId") or ""
+        if not iid:
+            continue
+        display = it.get("displayName") or ""
+        if not display:
+            label = it.find("Label")
+            if label is not None:
+                # Match backend `_index_item_signatures` (reasoning_diff.py:230-234):
+                # an empty <Label/> yields "" rather than skipping the field.
+                display = label.text or ""
+        parent = it.get("parentItemRef") or ""
+        out[iid] = ((display or "").strip(), parent.strip())
+    return out
+
+
+def _index_contexts_et(root: ET.Element) -> set:
+    ctx_defs = root.find("ContextDefinitions")
+    if ctx_defs is None:
+        return set()
+    return {el.get("contextId") for el in ctx_defs.findall("Context") if el.get("contextId")}
+
+
+def _index_statuses_et(root: ET.Element) -> set:
+    st_defs = root.find("StatusDefinitions")
+    if st_defs is None:
+        return set()
+    return {el.get("statusId") for el in st_defs.findall("Status") if el.get("statusId")}
+
+
+def _index_claim_kinds_et(root: ET.Element) -> dict:
+    out: dict[str, str] = {}
+    reasoning = root.find("Reasoning")
+    if reasoning is None:
+        return out
+    for c in reasoning.findall("Claim"):
+        cid = c.get("id") or ""
+        if cid:
+            out[cid] = c.get("kind") or ""
+    return out
+
+
+def _index_assumption_status_et(root: ET.Element) -> dict:
+    """Return {assumption_id: status_str} for all Assumption nodes."""
+    out: dict[str, str] = {}
+    reasoning = root.find("Reasoning")
+    if reasoning is None:
+        return out
+    for a in reasoning.findall("Assumption"):
+        aid = a.get("id") or ""
+        if aid:
+            out[aid] = a.get("status") or "holding"
+    return out
+
+
+def _index_reasoning_nodes_et(root: ET.Element, element: str) -> dict:
+    """Return {node_id: ET.Element} for Reasoning nodes of the given element type."""
+    out: dict[str, ET.Element] = {}
+    reasoning = root.find("Reasoning")
+    if reasoning is None:
+        return out
+    for n in reasoning.findall(element):
+        nid = n.get("id") or ""
+        if nid:
+            out[nid] = n
+    return out
+
+
+_ANCHOR_ATTRS_ET = frozenset({
+    "itemRefs", "itemRef", "contextRefs", "contextRef", "statusRef",
+    "calcRef", "scenarioRef", "customDimensions", "kind", "parentClaimRef",
+})
+
+
+def _node_anchor_attrs_changed_et(p: ET.Element, w: ET.Element) -> set[str]:
+    """Return anchor attrs that differ between parent/working ET nodes."""
+    changed: set[str] = set()
+    keys = set(p.attrib.keys()) | set(w.attrib.keys())
+    for k in keys:
+        if k not in _ANCHOR_ATTRS_ET:
+            continue
+        if p.attrib.get(k) != w.attrib.get(k):
+            changed.add(k)
+    return changed
+
+
+def _split_csv_et(s: str | None) -> list:
+    if not s:
+        return []
+    return [x.strip() for x in s.split(",") if x.strip()]
+
+
+def _build_changed_set(parent_root: ET.Element, working_root: ET.Element) -> set:
+    """Compute the set of _ChangedRef entries representing all changes between parent and working."""
+    changed: set[_ChangedRef] = set()
+
+    # Snapshot drift: Value changes (keyed by item, ctx, status, scenario, dims)
+    pv = _index_values_et(parent_root)
+    wv = _index_values_et(working_root)
+    for k, v in wv.items():
+        if pv.get(k) != v:
+            item, ctx, status, scenario, dims = k
+            ref = f"value:{item}@{ctx}/{status}"
+            if scenario:
+                ref += f"#scen={scenario}"
+            if dims:
+                ref += f"|dims={dims}"
+            changed.add(_ChangedRef("snapshot", ref))
+
+    # Semantic drift: CalcDef formula or attribute changes
+    pc = _index_calcs_et(parent_root)
+    wc = _index_calcs_et(working_root)
+    for cid, w_repr in wc.items():
+        if pc.get(cid) != w_repr:
+            changed.add(_ChangedRef("semantic", f"calc:{cid}"))
+
+    # Structural drift: Item removals (with rename heuristic)
+    p_items = _index_items_et(parent_root)
+    w_items = _index_items_et(working_root)
+    p_sigs = _index_item_signatures_et(parent_root)
+    w_sigs = _index_item_signatures_et(working_root)
+    removed = p_items - w_items
+    added = w_items - p_items
+
+    suppress_removed: set[str] = set()
+    matched_added: set[str] = set()
+    for old_id in sorted(removed):
+        old_sig = p_sigs.get(old_id)
+        if not old_sig or not old_sig[0]:
+            continue
+        for new_id in sorted(added):
+            if new_id in matched_added:
+                continue
+            if w_sigs.get(new_id) == old_sig:
+                changed.add(_ChangedRef("rename", f"item:{old_id}->{new_id}"))
+                suppress_removed.add(old_id)
+                matched_added.add(new_id)
+                break
+
+    for r in removed - suppress_removed:
+        changed.add(_ChangedRef("structural", f"item:{r}"))
+
+    # Structural drift: ContextDef / StatusDef removals
+    for cid in _index_contexts_et(parent_root) - _index_contexts_et(working_root):
+        changed.add(_ChangedRef("structural", f"context:{cid}"))
+    for sid in _index_statuses_et(parent_root) - _index_statuses_et(working_root):
+        changed.add(_ChangedRef("structural", f"status:{sid}"))
+
+    # Logical drift: Assumption status flipping to "broken"
+    pa = _index_assumption_status_et(parent_root)
+    wa = _index_assumption_status_et(working_root)
+    for aid, w_status in wa.items():
+        if w_status == "broken" and pa.get(aid) != "broken":
+            changed.add(_ChangedRef("logical", f"assumption:{aid}"))
+
+    return changed
+
+
+def _detect_kind_flips_et(parent_root: ET.Element, working_root: ET.Element) -> list:
+    pk = _index_claim_kinds_et(parent_root)
+    wk = _index_claim_kinds_et(working_root)
+    out: list[_DiffEntry] = []
+    for cid, new_kind in wk.items():
+        old_kind = pk.get(cid)
+        if old_kind is None:
+            continue
+        if old_kind != new_kind:
+            out.append(_DiffEntry(cid, "semantic", f"kind changed: {old_kind}->{new_kind}"))
+    return out
+
+
+def _compute_reasoning_diff_pair_et(
+    parent_root: ET.Element, working_root: ET.Element
+) -> list:
+    changed = _build_changed_set(parent_root, working_root)
+
+    # Per-anchor same-commit suppression
+    edited_anchor_attrs: dict[str, set[str]] = {}
+    for element in ("Claim", "Assumption", "Evidence"):
+        p_idx = _index_reasoning_nodes_et(parent_root, element)
+        w_idx = _index_reasoning_nodes_et(working_root, element)
+        for nid, w_node in w_idx.items():
+            p_node = p_idx.get(nid)
+            if p_node is None:
+                edited_anchor_attrs[nid] = set(_ANCHOR_ATTRS_ET)
+                continue
+            edited_anchor_attrs[nid] = _node_anchor_attrs_changed_et(p_node, w_node)
+
+    entries: list[_DiffEntry] = []
+    seen: set = set()
+
+    def _emit(node_id: str, kind: str, summary: str) -> None:
+        key = (node_id, kind, summary)
+        if key in seen:
+            return
+        seen.add(key)
+        entries.append(_DiffEntry(node_id, kind, summary))
+
+    def _suppressed(nid: str, anchor_attrs: set[str]) -> bool:
+        edited = edited_anchor_attrs.get(nid, set())
+        return bool(edited & anchor_attrs)
+
+    if not changed:
+        return entries
+
+    w_reasoning = working_root.find("Reasoning")
+    if w_reasoning is None:
+        return entries
+
+    for element in ("Claim", "Assumption"):
+        for n in w_reasoning.findall(element):
+            nid = n.get("id")
+            if nid is None:
+                continue
+
+            item_refs = _split_csv_et(n.get("itemRefs") or n.get("itemRef"))
+            ctx_refs = _split_csv_et(n.get("contextRefs") or n.get("contextRef"))
+            status_ref = n.get("statusRef")
+            calc_ref = n.get("calcRef")
+            anchor_scenario = n.get("scenarioRef")
+            anchor_dims = _canonical_dims_et(n.get("customDimensions"))
+
+            for cr in changed:
+                if cr.drift_kind == "snapshot":
+                    body = cr.ref[len("value:"):]
+                    cr_dims = ""
+                    if "|dims=" in body:
+                        body, cr_dims = body.split("|dims=", 1)
+                    cr_scen = ""
+                    if "#scen=" in body:
+                        body, cr_scen = body.split("#scen=", 1)
+                    item, rest = body.split("@", 1)
+                    ctx, status = rest.split("/", 1)
+                    item_match = item in item_refs
+                    ctx_match = (not ctx_refs) or (ctx in ctx_refs)
+                    status_match = (not status_ref) or (status_ref == status)
+                    scen_match = (not anchor_scenario) or (anchor_scenario == cr_scen)
+                    dims_match = (not anchor_dims) or (anchor_dims == cr_dims)
+                    if item_match and ctx_match and status_match and scen_match and dims_match:
+                        if _suppressed(nid, {"itemRefs", "itemRef", "contextRefs",
+                                             "contextRef", "statusRef",
+                                             "scenarioRef", "customDimensions"}):
+                            continue
+                        _emit(nid, "snapshot", cr.ref)
+                elif cr.drift_kind == "semantic":
+                    if calc_ref and cr.ref == f"calc:{calc_ref}":
+                        if _suppressed(nid, {"calcRef"}):
+                            continue
+                        _emit(nid, "semantic", cr.ref)
+                elif cr.drift_kind == "structural":
+                    body = cr.ref
+                    if body.startswith("item:"):
+                        target = body[len("item:"):]
+                        if target in item_refs:
+                            if _suppressed(nid, {"itemRefs", "itemRef"}):
+                                continue
+                            _emit(nid, "structural", cr.ref)
+                    elif body.startswith("context:"):
+                        target = body[len("context:"):]
+                        if target in ctx_refs:
+                            if _suppressed(nid, {"contextRefs", "contextRef"}):
+                                continue
+                            _emit(nid, "structural", cr.ref)
+                    elif body.startswith("status:"):
+                        target = body[len("status:"):]
+                        if status_ref == target:
+                            if _suppressed(nid, {"statusRef"}):
+                                continue
+                            _emit(nid, "structural", cr.ref)
+                elif cr.drift_kind == "rename":
+                    body = cr.ref[len("item:"):]
+                    old_id, _, _new_id = body.partition("->")
+                    if old_id in item_refs:
+                        if _suppressed(nid, {"itemRefs", "itemRef"}):
+                            continue
+                        _emit(nid, "rename", cr.ref)
+
+    broken_assumptions = {
+        cr.ref[len("assumption:"):]
+        for cr in changed
+        if cr.drift_kind == "logical"
+    }
+    for a in w_reasoning.findall("Argument"):
+        if a.get("rel") != "depends_on":
+            continue
+        target = a.get("to")
+        if target in broken_assumptions:
+            src = a.get("from")
+            if not src:
+                continue
+            if edited_anchor_attrs.get(src):
+                continue
+            _emit(src, "logical", f"depended-on assumption '{target}' flipped to broken")
+
+    return entries
+
+
+def _compute_reasoning_diff(
+    parent_root: ET.Element,
+    working_root: ET.Element,
+    branch_base_root: ET.Element | None = None,
+) -> list:
+    """Return one _DiffEntry per Reasoning node whose anchor was touched.
+
+    Per-anchor same-commit suppression and Phase 2 drift coverage (renames,
+    Context/Status removals, kind flips). When `branch_base_root` is supplied,
+    drift accumulates across both branch_base→parent and parent→working.
+    """
+    entries = _compute_reasoning_diff_pair_et(parent_root, working_root)
+    entries.extend(_detect_kind_flips_et(parent_root, working_root))
+
+    if branch_base_root is not None:
+        base_entries = _compute_reasoning_diff_pair_et(branch_base_root, parent_root)
+        base_entries.extend(_detect_kind_flips_et(branch_base_root, parent_root))
+        existing = {(e.node_id, e.drift_kind, e.change_summary) for e in entries}
+        for e in base_entries:
+            key = (e.node_id, e.drift_kind, e.change_summary)
+            if key in existing:
+                continue
+            existing.add(key)
+            entries.append(e)
+
+    return entries
+
+
+@click.command("reasoning-diff")
+@click.argument("file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--accept",
+    is_flag=True,
+    default=False,
+    help="Print warnings but exit 0 (acknowledge and continue).",
+)
+@click.option(
+    "--since-branch-base",
+    "since_branch_base",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help=(
+        "Path to a third .deepcell file representing the branch base. When "
+        "supplied, drift is computed across both branch_base->HEAD and "
+        "HEAD->working intervals so accumulated commits surface."
+    ),
+)
+def reasoning_diff(
+    file: Path, accept: bool, since_branch_base: Path | None
+) -> None:
+    """Warn when an edit moved something a Claim was anchored to.
+
+    Compares FILE at git HEAD against the working tree. Run it before
+    committing: it exits non-zero if any Claim is potentially affected, so a
+    git pre-commit hook can block. Pass --accept to acknowledge and exit zero
+    anyway, or --since-branch-base PATH to also include drift accumulated
+    since the supplied branch-base file.
+
+    Takes a local path, not a workspace filename — it reads git.
+    For a workspace premise change and its cross-surface reassessment, read
+    `deepcell guide revise/premise-change`.
+    """
+    # Locate the git repo for FILE
+    try:
+        repo_root = subprocess.check_output(
+            ["git", "-C", str(file.parent), "rev-parse", "--show-toplevel"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except subprocess.CalledProcessError:
+        click.echo(
+            f"warning: {file} is not in a git repo; skipping reasoning-diff", err=True
+        )
+        return
+
+    # Path of FILE relative to repo root
+    try:
+        rel_path = file.resolve().relative_to(Path(repo_root).resolve())
+    except ValueError:
+        click.echo(f"warning: {file} is not inside {repo_root}; skipping", err=True)
+        return
+
+    # Read parent (git HEAD) version. If the file has no history, exit cleanly.
+    try:
+        parent_xml = subprocess.check_output(
+            ["git", "-C", repo_root, "show", f"HEAD:{rel_path.as_posix()}"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        )
+    except subprocess.CalledProcessError:
+        # File is untracked / new — nothing to diff against
+        return
+
+    working_xml = file.read_text()
+
+    parent_root = _parse_xml_string(parent_xml)
+    working_root = _parse_xml_string(working_xml)
+    branch_base_root = None
+    if since_branch_base is not None:
+        branch_base_xml = since_branch_base.read_text()
+        branch_base_root = _parse_xml_string(branch_base_xml)
+    entries = _compute_reasoning_diff(parent_root, working_root, branch_base_root)
+
+    if not entries:
+        return
+
+    click.echo(
+        click.style(
+            "Reasoning diff — Claims potentially affected by this change:",
+            fg="yellow",
+        ),
+        err=True,
+    )
+    for e in entries:
+        click.echo(f"  * {e.node_id}  [{e.drift_kind}]  {e.change_summary}", err=True)
+
+    if accept:
+        return  # exit 0
+
+    click.echo(
+        click.style(
+            "Pass --accept to acknowledge and continue, or edit the affected Claims first.",
+            fg="red",
+        ),
+        err=True,
+    )
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# `deepcell reasoning ...` group — API-backed (workspace FILENAME)
+# ---------------------------------------------------------------------------
+#
+# Every command in this file takes a workspace-relative FILENAME (see the
+# module docstring); the difference here is *where the work happens*. The
+# `claim`/`assumption` groups above fetch the XML and parse it in-process, while
+# this group posts it to the Jingwei API and renders the response.
+# `reasoning-diff` is the only local-path command in the file.
+
+
+@click.group()
+def reasoning() -> None:
+    """Read and edit the Claim / Assumption / Evidence graph in a document.
+
+    A .deepcell document records why it says what it says: Claims, the
+    Assumptions and Evidence they rest on, and the Argument edges between
+    them. These subcommands author that graph, inspect it, and check it.
+
+    \b
+    AUTHORING A WHOLE ARGUMENT? Use `reasoning apply`. A finished argument is
+    a dozen nodes and two dozen edges, and each add-* below is one round-trip;
+    `apply` sends them all in a single atomic call, in the order you list them,
+    so an Argument may name a node declared earlier in the same batch:
+      deepcell reasoning apply model.deepcell --ops '[{"op": "add_claim", ...}]'
+    The single add-* commands stay the right tool for one node, and for
+    learning an op's fields from `--help` rather than from JSON.
+
+    \b
+    Declare:  set-conclusion (which Claim is the document's answer — point
+              <Reasoning> at the apex thesis as soon as add-claim has
+              authored it, then build the argument for it)
+    Add:      add-claim, add-assumption, add-evidence, add-argument
+              (or all of them at once: apply)
+    Revise:   supersede-claim / supersede-assumption (keeps the old node as
+              history — the default way to change what a Claim asserts),
+              update-* (corrects a node in place)
+    Remove:   delete-* (erases the record; prefer supersede)
+    Inspect:  graph (Mermaid/DOT), impact (what breaks if a claim falls)
+    Check:    lint (structural rules; --strict for hygiene warnings too)
+
+    `set-conclusion` does not create a Claim — author the apex `thesis` with
+    `add-claim`, then point `<Reasoning>` at it.
+
+    Read `deepcell guide revise/reasoning` before writing your first node, and
+    `deepcell guide verify/review` when reviewing a finished document.
+    `deepcell claim` and `deepcell assumption` hold the per-node read views.
+    """
+
+
+# --- Mermaid renderer -------------------------------------------------------
+
+# Mermaid classDef for each node type. Driven by the `type` field on the
+# /reasoning/graph response.
+_MERMAID_NODE_CLASS = {
+    "claim": "claim",
+    "assumption": "assumption",
+    "evidence": "evidence",
+}
+
+_MERMAID_CLASSDEFS = (
+    "  classDef claim fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;\n"
+    "  classDef assumption fill:#fef3c7,stroke:#b45309,color:#78350f;\n"
+    "  classDef evidence fill:#dcfce7,stroke:#15803d,color:#14532d;\n"
+)
+
+# Edge styling per Argument @rel — color/dasharray. Cosmetic; safe to extend.
+_MERMAID_LINK_STYLE = {
+    "supports": "stroke:#16a34a,stroke-width:2px",
+    "refutes": "stroke:#dc2626,stroke-width:2px",
+    "contradicts": "stroke:#dc2626,stroke-width:2px,stroke-dasharray:4 2",
+    "depends_on": "stroke:#1d4ed8,stroke-width:2px,stroke-dasharray:4 2",
+    "derives_from": "stroke:#737373,stroke-width:1.5px",
+    "supersedes": "stroke:#525252,stroke-width:1.5px",
+    "variant_of": "stroke:#7c3aed,stroke-width:1.5px",
+    "references": "stroke:#a3a3a3,stroke-width:1px",
+}
+
+
+def _mermaid_id(raw: str) -> str:
+    """Sanitize a node id so it parses as a Mermaid identifier."""
+    out = []
+    for ch in raw:
+        if ch.isalnum() or ch == "_":
+            out.append(ch)
+        else:
+            out.append("_")
+    sanitized = "".join(out) or "node"
+    if sanitized[0].isdigit():
+        sanitized = "n_" + sanitized
+    return sanitized
+
+
+def _mermaid_label(label: str, node_id: str) -> str:
+    """Quote and escape a node label so Mermaid accepts it inside [\"...\"]."""
+    text = label or node_id
+    # Single-line, length-bounded so the graph stays readable.
+    text = " ".join(text.split())
+    if len(text) > 60:
+        text = text[:57] + "..."
+    return text.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _arrow_with_label(rel: str) -> str:
+    # Mermaid edge with hover/inline label: -- "rel" -->
+    safe_rel = rel.replace('"', '\\"')
+    return f'-- "{safe_rel}" -->'
+
+
+def _render_mermaid(graph: dict) -> str:
+    nodes = graph.get("nodes", []) or []
+    edges = graph.get("edges", []) or []
+
+    lines: list[str] = ["flowchart TD"]
+    lines.append(_MERMAID_CLASSDEFS.rstrip("\n"))
+
+    # id_map: original id → sanitized id; collisions resolved by suffixing.
+    id_map: dict[str, str] = {}
+    used: set[str] = set()
+    for n in nodes:
+        raw_id = n.get("id", "")
+        base = _mermaid_id(raw_id)
+        candidate = base
+        i = 2
+        while candidate in used:
+            candidate = f"{base}_{i}"
+            i += 1
+        used.add(candidate)
+        id_map[raw_id] = candidate
+
+    for n in nodes:
+        nid = id_map.get(n.get("id", ""), "")
+        if not nid:
+            continue
+        label = _mermaid_label(n.get("label") or n.get("id") or "", n.get("id", ""))
+        lines.append(f'  {nid}["{label}"]')
+
+    # Per-node class assignments — one line is fine but per-node is clearest.
+    for n in nodes:
+        nid = id_map.get(n.get("id", ""), "")
+        cls = _MERMAID_NODE_CLASS.get(n.get("type", ""))
+        if nid and cls:
+            lines.append(f"  class {nid} {cls};")
+
+    # Edges + linkStyle. linkStyle is positional, so collect (index, style).
+    link_style_lines: list[str] = []
+    for idx, e in enumerate(edges):
+        src = id_map.get(e.get("source", ""))
+        tgt = id_map.get(e.get("target", ""))
+        rel = e.get("type", "")
+        if not (src and tgt and rel):
+            continue
+        lines.append(f"  {src} {_arrow_with_label(rel)} {tgt}")
+        style = _MERMAID_LINK_STYLE.get(rel)
+        if style:
+            link_style_lines.append(f"  linkStyle {idx} {style};")
+
+    lines.extend(link_style_lines)
+    return "\n".join(lines) + "\n"
+
+
+# --- DOT (Graphviz) renderer ------------------------------------------------
+
+_DOT_NODE_STYLE = {
+    "claim": 'shape=box, style="rounded,filled", fillcolor="#dbeafe", color="#1d4ed8"',
+    "assumption": 'shape=octagon, style=filled, fillcolor="#fef3c7", color="#b45309"',
+    "evidence": 'shape=note, style=filled, fillcolor="#dcfce7", color="#15803d"',
+}
+
+_DOT_EDGE_STYLE = {
+    "supports": 'color="#16a34a", penwidth=2',
+    "refutes": 'color="#dc2626", penwidth=2',
+    "contradicts": 'color="#dc2626", penwidth=2, style=dashed',
+    "depends_on": 'color="#1d4ed8", penwidth=2, style=dashed',
+    "derives_from": 'color="#737373"',
+    "supersedes": 'color="#525252"',
+    "variant_of": 'color="#7c3aed"',
+    "references": 'color="#a3a3a3"',
+}
+
+
+def _dot_escape(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _render_dot(graph: dict) -> str:
+    nodes = graph.get("nodes", []) or []
+    edges = graph.get("edges", []) or []
+
+    lines: list[str] = ["digraph reasoning {", '  rankdir="TB";', '  node [fontname="Helvetica", fontsize=10];', '  edge [fontname="Helvetica", fontsize=9];']
+
+    for n in nodes:
+        nid = _dot_escape(n.get("id", ""))
+        if not nid:
+            continue
+        label = _dot_escape(n.get("label") or n.get("id") or "")
+        style = _DOT_NODE_STYLE.get(n.get("type", ""), "")
+        attrs = f'label="{label}"'
+        if style:
+            attrs += f", {style}"
+        lines.append(f'  "{nid}" [{attrs}];')
+
+    for e in edges:
+        src = _dot_escape(e.get("source", ""))
+        tgt = _dot_escape(e.get("target", ""))
+        rel = e.get("type", "")
+        if not (src and tgt and rel):
+            continue
+        attrs = [f'label="{_dot_escape(rel)}"']
+        if rel in _DOT_EDGE_STYLE:
+            attrs.append(_DOT_EDGE_STYLE[rel])
+        lines.append(f'  "{src}" -> "{tgt}" [{", ".join(attrs)}];')
+
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+@reasoning.command("graph")
+@click.argument("filename")
+@click.option(
+    "--syntax",
+    "graph_syntax",
+    type=click.Choice(["mermaid", "dot"]),
+    default="mermaid",
+    help="Graph syntax to emit. Use the global -f json for the raw graph payload.",
+)
+@pass_ctx
+def reasoning_graph_cmd(ctx: Ctx, filename: str, graph_syntax: str) -> None:
+    """Render the Argument graph from FILENAME as Mermaid (default) or DOT.
+
+    Pipe the output into a markdown PR comment, a Mermaid renderer, or
+    `dot -Tsvg` to visualize Claims/Assumptions/Evidence and the Arguments
+    that connect them. `-f json` returns the raw graph payload (nodes,
+    edges, metadata).
+    """
+    xml = _get_xml(ctx, filename)
+    data = ctx.client.post("/reasoning/graph", json={"xml": xml})
+    if ctx.fmt == "json":
+        output(data, "json")
+        return
+    if graph_syntax == "dot":
+        print_plain(_render_dot(data))
+    else:
+        print_plain(_render_mermaid(data))
+    # Malformed nodes are dropped server-side with a warning in
+    # metadata.warnings — without echoing it the rendered graph reads as
+    # authoritative while silently incomplete.
+    meta = data.get("metadata") if isinstance(data, dict) else None
+    for w in (meta or {}).get("warnings") or []:
+        echo_warning(str(w))
+
+
+# --- reasoning lint ---------------------------------------------------------
+
+
+_SEVERITY_COLOR = {"error": "red", "warn": "yellow"}
+
+
+def _format_lint_findings_plain(data: dict) -> str:
+    """Format /reasoning/lint findings for human reading.
+
+    One finding per line, plus a final summary. Empty result → empty string
+    (matches `reasoning-diff`'s quiet-success convention). Severity color
+    is suppressed when stdout is not a TTY so piped output stays clean.
+    """
+    findings = data.get("findings", []) or []
+    counts = data.get("counts", {}) or {}
+    if not findings:
+        return ""
+    use_color = sys.stdout.isatty()
+    lines = []
+    for f in findings:
+        sev = f.get("severity", "warn")
+        marker = (
+            click.style(sev, fg=_SEVERITY_COLOR.get(sev, "yellow"))
+            if use_color else sev
+        )
+        rule = f.get("rule", "")
+        tid = f.get("target_id", "")
+        msg = f.get("message", "")
+        lines.append(f"{marker}  [{rule}{rule_citation(f)}]  {tid}: {msg}")
+    err_n = counts.get("error", 0)
+    warn_n = counts.get("warn", 0)
+    lines.append("")
+    lines.append(f"{err_n} error(s), {warn_n} warning(s)")
+    footer = cited_rules_footer(findings)
+    if footer:
+        lines.append(footer)
+    return "\n".join(lines)
+
+
+@reasoning.command("lint")
+@click.argument("filename")
+@click.option(
+    "--strict",
+    is_flag=True,
+    help="Exit non-zero on warn-level findings too "
+    "(default: only error-level findings fail).",
+)
+@pass_ctx
+def reasoning_lint_cmd(ctx: Ctx, filename: str, strict: bool) -> None:
+    """Lint the <Reasoning> section of FILENAME for structural issues.
+
+    Runs the full read-only rule set (orphan claims, single-evidence funnels,
+    missing required risk attrs, Body↔itemRefs drift, missing @calcRef anchors,
+    unanchored claims/assumptions, attribute
+    typos, exclusivity assertions, dangling sensitivity refs, missing apex
+    recommendation). Exits non-zero when any error-level finding is produced;
+    warn-level findings are hygiene nudges and exit 0 unless --strict. Wire
+    `--strict` into pre-commit hooks the same way as `reasoning-diff`.
+    `-f json` returns the raw payload (findings + counts).
+    """
+    xml = _get_xml(ctx, filename)
+    data = ctx.client.post("/reasoning/lint", json={"xml": xml})
+    if ctx.fmt == "json":
+        output(data, "json")
+    else:
+        text = _format_lint_findings_plain(data)
+        if text:
+            print_plain(text)
+    findings = data.get("findings") or []
+    errors = [f for f in findings if f.get("severity") == "error"]
+    if errors or (strict and findings):
+        sys.exit(1)
+
+
+# --- reasoning impact -------------------------------------------------------
+
+
+@reasoning.command("impact", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("claim_id")
+@pass_ctx
+def reasoning_impact_cmd(ctx: Ctx, filename: str, claim_id: str) -> None:
+    """Walk Argument edges from CLAIM_ID and list downstream nodes affected if it's falsified.
+
+    Companion to `assumption impact` (single-hop) — `reasoning impact` is a
+    graph walk that surfaces transitive Claims/Assumptions that depend_on,
+    derive_from, support, or are variant_of the falsified claim. Each
+    returned node carries its `dependency_path` — the chain of @rel labels
+    from the node back to CLAIM_ID.
+
+    Both impact commands are workspace-backed and take a workspace-relative
+    FILENAME (matching the `reasoning graph`/`lint` pattern). The local Git
+    command is `reasoning-diff`. `-f json` returns the raw `{nodes: [...]}`
+    payload. Continue with `deepcell guide revise/premise-change`.
+    """
+    xml = _get_xml(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/query",
+        json={"xml": xml, "kind": "claim_impact", "id": claim_id},
+    )
+    if ctx.fmt == "json":
+        output(data, "json")
+        return
+    nodes = data.get("nodes", []) if isinstance(data, dict) else []
+    if not nodes:
+        return
+    for n in nodes:
+        nid = n.get("id", "")
+        ntype = n.get("type", "")
+        kind = n.get("kind")
+        label = n.get("label", "")
+        path = "->".join(n.get("dependency_path", []) or [])
+        marker = f"{ntype}/{kind}" if kind else ntype
+        if path:
+            click.echo(f"{nid}  [{marker}]  {label}  ({path})")
+        else:
+            click.echo(f"{nid}  [{marker}]  {label}")
+
+
+# --- reasoning add-* --------------------------------------------------------
+#
+# Each add-* subcommand reads the .deepcell XML, sends a single
+# `POST /reasoning/edit` with `op="add_<element>"` and a payload of
+# camelCase Pydantic field names (see backend/jingwei_api/utils/reasoning_pydantic.py
+# lines 88-172). The backend's `_pyd_to_canonical` (reasoning.py:242-266)
+# rewrites the payload into the canonical XML-dict shape, so the CLI just
+# needs to forward the flat dict verbatim and strip None values.
+#
+# Choice values mirror backend/src/core/constants/reasoning.py.
+# Sync with backend/src/core/constants/reasoning.py — if this list drifts,
+# `deepcell reasoning add-*` will reject values the backend would accept.
+_CLAIM_KINDS = (
+    "thesis", "risk", "catalyst", "counter", "question",
+    "market_consensus",
+)
+_ARGUMENT_RELS = (
+    "supports", "refutes", "depends_on", "derives_from",
+    "variant_of", "supersedes", "contradicts", "references", "answers",
+)
+_SEVERITY_VALUES = ("low", "med", "high")
+
+#: Mirrors ``NOTATIONS`` in ``backend/src/core/prose/body.py``. Declared here
+#: as a ``Choice`` so a typo is refused locally rather than coming back as a
+#: 422, the same standard ``BINDING_KINDS`` is held to in ``deck.py``.
+#:
+#: A reasoning body defaults to ``text`` — that is what every existing one
+#: already was, and re-reading the corpus as markdown would change what 11
+#: documents say without anyone editing them. Declaring ``markdown`` is how an
+#: author opts a body in, and it is the only way to stop `**0.397**` rendering
+#: as four visible asterisks.
+_BODY_NOTATIONS = ("markdown", "text")
+
+#: What a Label is *for*, said where the author is about to write one. The
+#: standard itself is `deepcell ref claim` (per kind) and the agent prompt;
+#: this is the one-line reminder at the point of use, and it is shared so the
+#: seven options that take a Label cannot drift into seven standards.
+_LABEL_HELP = (
+    "The finding itself, not the subject it concerns — \"Working capital is a "
+    "source of cash\", not \"Working capital\". Renders as the reasoning "
+    "outline row, and a Deck may bind it as a slide headline."
+)
+
+_BODY_NOTATION_HELP = (
+    "What the <Body> IS: markdown or literal text. Declared, never sniffed — "
+    "no reader guesses from the bytes. Omitted leaves it as it was."
+)
+#: `@strength` — how strongly a claim is held, qualitatively. Mirrors
+#: `src.core.constants.reasoning.CLAIM_STRENGTHS`. Independent of
+#: `--confidence`, which is the same judgement as a number: the format defines
+#: both and says they may coexist, so neither is offered as an alias for the
+#: other.
+_CLAIM_STRENGTHS = ("low", "med", "high")
+_CLAIM_STATUSES = ("draft", "active", "superseded", "falsified", "revoked")
+_ASSUMPTION_STATUSES = ("holding", "uncertain", "broken", "superseded")
+
+# Assumption lifecycle dates. Both were documented in the Assumption attribute
+# table with no way to set them, so `--broken-at` was reached for in good faith
+# and answered with "No such option" (guide eval, `reasoning` task-2). They are
+# plain ISO date attributes: the backend already allow-lists and ISO-validates
+# `@verifiedAt` / `@brokenAt`, so this is a CLI-side gap only.
+_VERIFIED_AT_HELP = (
+    "ISO date (YYYY-MM-DD) this assumption was last confirmed to still hold "
+    "(@verifiedAt). Records WHEN it was checked; --status holding records that "
+    "it stands."
+)
+_BROKEN_AT_HELP = (
+    "ISO date (YYYY-MM-DD) this assumption was found no longer to hold "
+    "(@brokenAt). Records WHEN it failed; --status broken records THAT it "
+    "failed — set both when actuals contradict an assumption."
+)
+
+def _get_xml_with_revision(ctx: Ctx, filename: str) -> tuple[str, str | None]:
+    """Read the document and the revision it was read at.
+
+    Every `reasoning add-*`/`update-*` is fetch → `/reasoning/edit` →
+    POST-full-content, so the revision has to travel with the XML or the write
+    back is unguarded and overwrites whatever landed in between (#1217).
+    """
+    from deepcell_cli.revision import fetch_xml_with_revision
+
+    return fetch_xml_with_revision(ctx, ctx.require_workspace(), filename)
+
+
+def _persist_edit_result(
+    ctx: Ctx, filename: str, data: Any, revision: str | None = None
+) -> None:
+    """Write the post-edit XML back to the workspace and print the result.
+
+    `/reasoning/edit` and the workspace write are two separate calls; if the
+    second fails after the first succeeds, the user has no persisted state
+    but a successful-looking edit. Surface that explicitly so the user knows
+    to retry the write rather than re-run the whole add-* command (which
+    would re-apply the edit to a stale tree).
+
+    ``revision`` makes the write a compare-and-swap against the fetch, so a
+    concurrent change to this file is refused (409) instead of being silently
+    replaced by our copy of the pre-edit document.
+
+    The ``-m`` / ``--title`` the caller typed travel with it. Without them
+    this path sent no message at all and the server fell through to ``Update
+    <filename>`` — so the family editing the Claims and Assumptions, the one
+    place where "why did this change" IS the subject matter, recorded neither
+    the reason nor even which operation ran (#1717).
+    """
+    if not isinstance(data, dict):
+        raise click.ClickException("Unexpected response shape from /reasoning/edit.")
+    new_xml = data.get("xml", "")
+    if not new_xml:
+        raise click.ClickException("Server returned empty XML after edit.")
+    slug = ctx.require_workspace()
+    from deepcell_cli.errors import APIError
+    from deepcell_cli.revision import raise_if_stale, write_body
+
+    title, rationale = write_message()
+    try:
+        write_result = ctx.client.post(
+            f"/workspaces/{slug}/files/{filename}",
+            json=write_body(new_xml, revision, title=title, rationale=rationale),
+        )
+    except Exception as exc:
+        # A stale-revision 409 is not "the workspace is broken, retry the
+        # write" — replaying this XML would be the lost update. It gets its
+        # own message; everything else keeps the pre-existing one.
+        if isinstance(exc, APIError):
+            raise_if_stale(exc, filename=filename)
+        raise click.ClickException(
+            f"Edit succeeded server-side but persisting to "
+            f"{slug}/{filename} failed: {exc}. The edit was NOT saved — "
+            "re-run the command after resolving the workspace error."
+        ) from exc
+    output(data.get("result", {}), ctx.fmt)
+    # #1171 — a retried add whose first attempt landed server-side succeeds
+    # idempotently; tell the caller no second node was created.
+    if isinstance(data.get("result"), dict) and data["result"].get("already_existed"):
+        echo_info(
+            "node already existed with identical content — nothing new was "
+            "added (idempotent retry)"
+        )
+    # Surface lint findings (warn-level — error-level findings would have
+    # raised an HTTPException with a structured detail before reaching here).
+    # On stderr: stdout carries the structured result (pure JSON in -f json).
+    findings = data.get("findings") or data.get("result", {}).get("findings") or []
+    if findings:
+        click.echo("Findings:", err=True)
+        for f in findings:
+            sev = f.get("severity", "warn")
+            click.echo(
+                f"  [{sev}] {f.get('rule')}{rule_citation(f)}: "
+                f"{f.get('message')}{provenance(f)}",
+                err=True,
+            )
+        footer = cited_rules_footer(findings)
+        if footer:
+            click.echo(footer, err=True)
+
+    # What to do next, as opposed to what is wrong now. The server defers a
+    # warning it would be unfair to raise yet (an Argument cannot exist before
+    # the node it points at) and states it forward instead.
+    for step in (data.get("result") or {}).get("next_steps") or []:
+        echo_info(step)
+    errors = echo_validation(write_result)
+    sha = write_result.get("commit_sha") if isinstance(write_result, dict) else None
+    sha_part = f" (commit {str(sha)[:8]})" if sha else ""
+    if errors:
+        echo_warning(
+            f"'{filename}' saved{sha_part} with {len(errors)} validation "
+            "error(s) — fix the errors above"
+        )
+        raise click.exceptions.Exit(1)
+    echo_success(f"'{filename}' saved{sha_part}")
+
+
+# The coverage anchor, as flags, declared once.
+#
+# Coverage is what a node is ABOUT: Item x Context x Status x Scenario x
+# CustomDimensions -- the same five dimensions a cell has. The format has
+# always carried all five and the CLI reached three of them: `--context-refs`
+# was on 2 of the 8 write commands, and `--scenario-ref` / `--custom-dimensions`
+# on none at all, so a five-dimension anchor could only be written by editing
+# XML by hand.
+#
+# Declared here so a ninth write command cannot quietly ship with three of the
+# five. `--item-refs` and `--status-ref` stay on their commands: their help
+# text is command-specific (one explains `unanchored_claim`, the other warns
+# it is not the lifecycle `--status`).
+#
+# These say what a claim RANGES OVER. To state a number the model holds, cite
+# the cell inside the body -- `[[deepcell:cell/Item[Context]#status]]` through
+# `--body` -- which needs no flag of its own. See
+# `deepcell guide orient/surface-ownership`.
+_CONTEXT_REFS_OPTION = click.option(
+    "--context-refs", "context_refs", default=None,
+    help="Comma-separated context (period) ids this node reasons across.",
+)
+_SCENARIO_REF_OPTION = click.option(
+    "--scenario-ref", "scenario_ref", default=None,
+    help="Scenario id this node is about, when it holds only in one world.",
+)
+_CUSTOM_DIMENSIONS_OPTION = click.option(
+    "--custom-dimensions", "custom_dimensions", default=None,
+    help="Custom dimension members as `dim:member;dim2:member2` — the fifth "
+    "axis of the anchor (e.g. `region:emea`).",
+)
+
+
+def _coverage_anchor_options(f):
+    """`--context-refs`, `--scenario-ref`, `--custom-dimensions`, in that order."""
+    for option in (
+        _CUSTOM_DIMENSIONS_OPTION, _SCENARIO_REF_OPTION, _CONTEXT_REFS_OPTION,
+    ):
+        f = option(f)
+    return f
+
+
+def _narrow_anchor_options(f):
+    """The two a command that already declares `--context-refs` still lacks."""
+    for option in (_CUSTOM_DIMENSIONS_OPTION, _SCENARIO_REF_OPTION):
+        f = option(f)
+    return f
+
+
+#: Batch entries name their verb ``op`` (the `/reasoning/edit` spelling) while
+#: `defs apply` names it ``kind``. The two batches are separate doors — a
+#: reasoning kind is refused by `defs apply`'s request schema, which is a
+#: tagged union of the structural ops only — but an agent moving between them
+#: carries the vocabulary across, and being answered "unknown op: ''" over a
+#: spelling costs exactly the round the batch just saved. So both spellings are
+#: accepted here, and the same for the field bag, which `defs apply` calls
+#: ``defaults`` and this route calls ``payload``.
+def _normalize_reasoning_ops(payload: Any) -> list[dict[str, Any]]:
+    """Coerce a `reasoning apply` payload into `/reasoning/edit` batch entries."""
+    if isinstance(payload, dict):
+        ops = payload.get("ops")
+        if ops is None:
+            raise click.ClickException(
+                "ops JSON object has no 'ops' key. Pass either a bare array "
+                'of ops or {"ops": [...]}.'
+            )
+    else:
+        ops = payload
+    if not isinstance(ops, list):
+        raise click.ClickException(
+            'ops must be a JSON array, or an object with an "ops" array.'
+        )
+    if not ops:
+        raise click.ClickException("ops list is empty — nothing to apply.")
+
+    out: list[dict[str, Any]] = []
+    for i, op in enumerate(ops):
+        if not isinstance(op, dict):
+            raise click.ClickException(f"op {i} is not a JSON object.")
+        entry = dict(op)
+        if "op" not in entry and "kind" in entry:
+            entry["op"] = entry.pop("kind")
+        if "payload" not in entry and "defaults" in entry:
+            entry["payload"] = entry.pop("defaults")
+        if not entry.get("op"):
+            # Deliberately does NOT name a kind: `test_op_reachability` reads
+            # string constants in real code positions out of this package, and
+            # a kind spelled here would be counted as one the CLI emits.
+            raise click.ClickException(
+                f"op {i} has no 'op' — each entry needs one, beside its "
+                "'payload'. Run `deepcell ref op` for the kinds and "
+                "their fields."
+            )
+        out.append(entry)
+    return out
+
+
+@reasoning.command("apply", cls=WriteCommand)
+@click.argument("filename")
+@click.option(
+    "--ops-file",
+    "ops_file",
+    default=None,
+    type=click.File("r"),
+    help="JSON file with an `ops` array (use '-' for stdin).",
+)
+@click.option(
+    "--ops",
+    "ops_inline",
+    default=None,
+    help="Inline ops JSON (same shapes as --ops-file).",
+)
+@pass_ctx
+def reasoning_apply_cmd(
+    ctx: Ctx,
+    filename: str,
+    ops_file: Any,
+    ops_inline: str | None,
+) -> None:
+    """Apply a batch of reasoning ops atomically.
+
+    \b
+    The whole argument in one call. Each `reasoning add-*` is a separate
+    round-trip, and a real argument is a dozen nodes and two dozen edges —
+    one eval run spent 69 of its 282 commands here, one node at a time.
+
+    \b
+    The payload is a JSON document of either form:
+      [{"op": "add_claim", "payload": {...}}, ...]            # bare array
+      {"ops": [{"op": "add_evidence", "payload": {...}}, ...]}
+
+    \b
+    Verbs are the `add_*` / `update_*` / `delete_*` / `supersede_*` /
+    `set_*` op kinds (`deepcell ref op`). Edge ops carry `from_id`,
+    `to_id` and `edge_rel` beside the payload rather than inside it:
+      {"op": "add_argument", "payload": {"from": "c_thesis",
+       "rel": "supports", "to": "c_growth"}}
+
+    \b
+    Order matters and is honoured: declare a node before the Argument that
+    points at it, in the same batch. The batch is atomic — one bad op applies
+    none of them and persists nothing, so a rejection is safe to fix and
+    re-send whole.
+
+    \b
+    `defs apply` is the other door and carries the structural kinds; a
+    reasoning kind sent there is refused by its request schema. Structure and
+    argument are two batched calls, not one mixed one — still two instead of
+    the two hundred a command per node costs.
+    """
+    if (ops_file is None) == (ops_inline is None):
+        raise click.UsageError("Provide exactly one of --ops-file or --ops.")
+
+    raw = ops_inline if ops_inline is not None else ops_file.read()
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"ops payload is not valid JSON: {exc}") from exc
+
+    ops = _normalize_reasoning_ops(parsed)
+
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={"op": "batch", "xml": xml, "ops": ops},
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("add-claim", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--id", "claim_id", required=True, help="New Claim id.")
+@click.option(
+    "--kind",
+    required=True,
+    type=click.Choice(_CLAIM_KINDS),
+    help="What the claim is: thesis (what you conclude), risk / catalyst "
+    "(what moves it, needs --probability), counter (the case against), "
+    "question (open), market_consensus (someone else's view, needs "
+    "--attribution). See `deepcell guide revise/reasoning`.",
+)
+@click.option("--label", default=None, help=f"<Label> text. {_LABEL_HELP}")
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("<Label>", "label"),
+)
+@click.option("--body", default=None, help="<Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("<Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option(
+    "--status-ref", default=None,
+    help="Model Status dimension id (e.g. actual / projected) — NOT the "
+    "claim lifecycle state (that is --status).",
+)
+@click.option(
+    "--calc-ref", default=None,
+    help="CalcDef id anchoring this claim to a formula in the model.",
+)
+@click.option(
+    "--item-refs", default=None,
+    help="Comma-separated item ids anchoring this claim to a Spreadsheet. "
+    "When Items exist, thesis/risk/catalyst claims need --item-refs or "
+    "--calc-ref, else unanchored_claim warns (they become invisible to "
+    "reasoning-diff and item-scoped queries). A qualitative no-grid file "
+    "does not invent Items; question/market_consensus are always exempt.",
+)
+@click.option(
+    "--probability", default=None, type=float,
+    help="Likelihood, 0-1 (required for kind=risk / catalyst).",
+)
+@click.option(
+    "--severity", default=None, type=click.Choice(_SEVERITY_VALUES),
+    help="Qualitative impact (required for kind=risk).",
+)
+@click.option(
+    "--confidence", default=None, type=float,
+    help="How strongly you hold this claim, 0-1.",
+)
+@click.option(
+    "--strength", default=None, type=click.Choice(_CLAIM_STRENGTHS),
+    help="How strongly the claim is held, qualitatively. Independent of "
+    "--confidence (the numeric form); a claim may carry both.",
+)
+@click.option(
+    "--parent-claim-ref", default=None,
+    help="Claim id this one hangs under (hierarchy, not an Argument edge).",
+)
+@click.option(
+    "--attribution", default=None,
+    help="Who holds this view (required for kind=market_consensus), "
+    "e.g. 'Bloomberg consensus, 2026-07'.",
+)
+@click.option(
+    "--status", default=None, type=click.Choice(_CLAIM_STATUSES),
+    help="Claim lifecycle state — NOT the model's Status dimension "
+    "(that is --status-ref).",
+)
+@_coverage_anchor_options
+@pass_ctx
+def reasoning_add_claim_cmd(
+    ctx: Ctx,
+    filename: str,
+    claim_id: str,
+    kind: str,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    status_ref: str | None,
+    calc_ref: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    probability: float | None,
+    severity: str | None,
+    confidence: float | None,
+    strength: str | None,
+    parent_claim_ref: str | None,
+    attribution: str | None,
+    status: str | None,
+) -> None:
+    """Add a new <Claim> to FILENAME's <Reasoning> section.
+
+    Anchor the claim to the model with --item-refs or --calc-ref so it can
+    be impact-traced later. See `deepcell ref claim` for what each kind
+    is for.
+    """
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label", required=True)
+    body = _resolve_text_option(body, body_file, "body")
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    payload = {
+        k: v for k, v in {
+            "id": claim_id,
+            "kind": kind,
+            "label_text": label,
+            "body_text": body,
+            "body_notation": body_notation,
+            "statusRef": status_ref,
+            "calcRef": calc_ref,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "probability": probability,
+            "severity": severity,
+            "confidence": confidence,
+            "strength": strength,
+            "parentClaimRef": parent_claim_ref,
+            "attribution": attribution,
+            "status": status,
+        }.items() if v is not None
+    }
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={"xml": xml, "op": "add_claim", "payload": payload},
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("add-assumption", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--id", "assumption_id", required=True, help="New Assumption id.")
+@click.option("--label", default=None, help=f"<Label> text. {_LABEL_HELP}")
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("<Label>", "label"),
+)
+@click.option("--body", default=None, help="<Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("<Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option(
+    "--status-ref",
+    default=None,
+    help="Model Status dimension id (e.g. actual / projected) — NOT the "
+    "assumption's lifecycle state (that is --status).",
+)
+@click.option(
+    "--calc-ref",
+    default=None,
+    help="CalcDef id anchoring this assumption to a formula in the model.",
+)
+@click.option(
+    "--item-refs", default=None,
+    help="Comma-separated item ids the assumption constrains. When a "
+    "Spreadsheet exists, omitting it triggers unanchored_assumption because "
+    "the premise cannot be item-impact-traced as actuals drift in. A "
+    "qualitative no-grid file and macro assumptions may legitimately omit it.",
+)
+@click.option(
+    "--confidence",
+    default=None,
+    type=float,
+    help="How strongly you hold this assumption, 0-1.",
+)
+@click.option(
+    "--status",
+    default=None,
+    type=click.Choice(_ASSUMPTION_STATUSES),
+    help="Assumption lifecycle state: holding until something contradicts it, "
+    "broken once actuals do, superseded when a newer assumption replaces it.",
+)
+@click.option("--verified-at", "verified_at", default=None, help=_VERIFIED_AT_HELP)
+@click.option("--broken-at", "broken_at", default=None, help=_BROKEN_AT_HELP)
+@click.option(
+    "--parent-claim-ref", default=None,
+    help="Claim id this assumption hangs under (hierarchy, not an Argument edge).",
+)
+@_coverage_anchor_options
+@pass_ctx
+def reasoning_add_assumption_cmd(
+    ctx: Ctx,
+    filename: str,
+    assumption_id: str,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    status_ref: str | None,
+    calc_ref: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    confidence: float | None,
+    status: str | None,
+    verified_at: str | None,
+    broken_at: str | None,
+    parent_claim_ref: str | None,
+) -> None:
+    """Add a new <Assumption> to FILENAME's <Reasoning> section."""
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label", required=True)
+    body = _resolve_text_option(body, body_file, "body")
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    payload = {
+        k: v for k, v in {
+            "id": assumption_id,
+            "label_text": label,
+            "body_text": body,
+            "body_notation": body_notation,
+            "statusRef": status_ref,
+            "calcRef": calc_ref,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "confidence": confidence,
+            "status": status,
+            "verifiedAt": verified_at,
+            "brokenAt": broken_at,
+            "parentClaimRef": parent_claim_ref,
+        }.items() if v is not None
+    }
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={"xml": xml, "op": "add_assumption", "payload": payload},
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+def _update_reasoning_node(
+    ctx: Ctx, filename: str, op: str, target_id: str | None, payload: dict,
+    address: dict | None = None,
+) -> None:
+    """Shared body for update-claim / update-assumption: require at least
+    one attribute, post the partial payload through /reasoning/edit, and
+    persist. The backend merges the payload into the existing node.
+
+    `address` is the edge triple `update-argument` may give instead of an id;
+    it rides on the request envelope beside `target_id`, never inside the
+    payload, because the payload is the patch and the triple is the address.
+    """
+    if not payload:
+        raise click.ClickException(
+            "Nothing to update — pass at least one attribute option "
+            "(e.g. --item-refs, --calc-ref, --label)."
+        )
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={
+            "xml": xml, "op": op, "target_id": target_id, "payload": payload,
+            **(address or {}),
+        },
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("update-claim", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("claim_id")
+@click.option(
+    "--kind",
+    default=None,
+    type=click.Choice(_CLAIM_KINDS),
+    help="Reclassify the claim — see `deepcell reasoning add-claim --help` "
+    "for what each kind means.",
+)
+@click.option(
+    "--label", default=None,
+    help=f"Replacement <Label> text. {_LABEL_HELP}",
+)
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Label>", "label"),
+)
+@click.option("--body", default=None, help="Replacement <Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option(
+    "--status-ref", default=None,
+    help="Model Status dimension id (e.g. actual / projected) — NOT the "
+    "claim lifecycle state (that is --status).",
+)
+@click.option(
+    "--calc-ref", default=None,
+    help="CalcDef id anchoring this claim to a formula in the model.",
+)
+@click.option(
+    "--item-refs", default=None,
+    help="Comma-separated item ids anchoring this claim to a Spreadsheet — "
+    "the fix for unanchored_claim when the file has Items.",
+)
+@click.option(
+    "--probability", default=None, type=float,
+    help="Likelihood, 0-1 (required for kind=risk / catalyst).",
+)
+@click.option(
+    "--severity", default=None, type=click.Choice(_SEVERITY_VALUES),
+    help="Qualitative impact (required for kind=risk).",
+)
+@click.option(
+    "--confidence", default=None, type=float,
+    help="How strongly you hold this claim, 0-1.",
+)
+@click.option(
+    "--strength", default=None, type=click.Choice(_CLAIM_STRENGTHS),
+    help="How strongly the claim is held, qualitatively. Independent of "
+    "--confidence (the numeric form); a claim may carry both.",
+)
+@click.option(
+    "--parent-claim-ref", default=None,
+    help="Claim id this one hangs under (hierarchy, not an Argument edge).",
+)
+@click.option(
+    "--attribution", default=None,
+    help="Who holds this view (required for kind=market_consensus).",
+)
+@click.option(
+    "--status", default=None, type=click.Choice(_CLAIM_STATUSES),
+    help="Claim lifecycle state — NOT the model's Status dimension "
+    "(that is --status-ref).",
+)
+@_coverage_anchor_options
+@pass_ctx
+def reasoning_update_claim_cmd(
+    ctx: Ctx,
+    filename: str,
+    claim_id: str,
+    kind: str | None,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    status_ref: str | None,
+    calc_ref: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    probability: float | None,
+    severity: str | None,
+    confidence: float | None,
+    strength: str | None,
+    parent_claim_ref: str | None,
+    attribution: str | None,
+    status: str | None,
+) -> None:
+    """Update attributes on an existing <Claim> CLAIM_ID in FILENAME.
+
+    Partial update: only the options you pass change; everything else on
+    the node is preserved. Typical use: anchor an existing claim
+    (`update-claim m.deepcell t1 --item-refs Revenue`).
+    """
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label")
+    body = _resolve_text_option(body, body_file, "body")
+    payload = {
+        k: v for k, v in {
+            "kind": kind,
+            "label_text": label,
+            "body_text": body,
+            "body_notation": body_notation,
+            "statusRef": status_ref,
+            "calcRef": calc_ref,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "probability": probability,
+            "severity": severity,
+            "confidence": confidence,
+            "strength": strength,
+            "parentClaimRef": parent_claim_ref,
+            "attribution": attribution,
+            "status": status,
+        }.items() if v is not None
+    }
+    _update_reasoning_node(ctx, filename, "update_claim", claim_id, payload)
+
+
+@reasoning.command("update-assumption", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("assumption_id")
+@click.option(
+    "--label", default=None,
+    help=f"Replacement <Label> text. {_LABEL_HELP}",
+)
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Label>", "label"),
+)
+@click.option("--body", default=None, help="Replacement <Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option(
+    "--status-ref",
+    default=None,
+    help="Model Status dimension id (e.g. actual / projected) — NOT the "
+    "assumption's lifecycle state (that is --status).",
+)
+@click.option(
+    "--calc-ref",
+    default=None,
+    help="CalcDef id anchoring this assumption to a formula in the model.",
+)
+@click.option(
+    "--item-refs", default=None,
+    help="Comma-separated item ids the assumption constrains — the fix for "
+    "unanchored_assumption when the file has Items.",
+)
+@click.option(
+    "--confidence",
+    default=None,
+    type=float,
+    help="How strongly you hold this assumption, 0-1.",
+)
+@click.option(
+    "--status",
+    default=None,
+    type=click.Choice(_ASSUMPTION_STATUSES),
+    help="Assumption lifecycle state: holding until something contradicts it, "
+    "broken once actuals do, superseded when a newer assumption replaces it.",
+)
+@click.option("--verified-at", "verified_at", default=None, help=_VERIFIED_AT_HELP)
+@click.option("--broken-at", "broken_at", default=None, help=_BROKEN_AT_HELP)
+@_coverage_anchor_options
+@pass_ctx
+def reasoning_update_assumption_cmd(
+    ctx: Ctx,
+    filename: str,
+    assumption_id: str,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    status_ref: str | None,
+    calc_ref: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    confidence: float | None,
+    status: str | None,
+    verified_at: str | None,
+    broken_at: str | None,
+) -> None:
+    """Update attributes on an existing <Assumption> ASSUMPTION_ID.
+
+    Partial update: only the options you pass change; everything else on
+    the node is preserved.
+
+    A lifecycle flip is a plain update, not a supersede: `--status broken`
+    records *that* the assumption failed, `--broken-at` records *when*.
+    Supersede only when replacing the assumption's content.
+    """
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label")
+    body = _resolve_text_option(body, body_file, "body")
+    payload = {
+        k: v for k, v in {
+            "label_text": label,
+            "body_text": body,
+            "body_notation": body_notation,
+            "statusRef": status_ref,
+            "calcRef": calc_ref,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "confidence": confidence,
+            "status": status,
+            "verifiedAt": verified_at,
+            "brokenAt": broken_at,
+        }.items() if v is not None
+    }
+    _update_reasoning_node(
+        ctx, filename, "update_assumption", assumption_id, payload,
+    )
+
+
+@reasoning.command("add-evidence", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--id", "evidence_id", required=True, help="New Evidence id.")
+@click.option("--source-ref", required=True, help="sourceId of a <Source> in <SourceDefinitions>.")
+@click.option("--excerpt", default=None, help="<Excerpt> text.")
+@click.option(
+    "--excerpt-file", "excerpt_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("<Excerpt>", "excerpt"),
+)
+@click.option("--at", "at", default=None, help="Position in the source (page:47, t:00:14:32, text:HEADING).")
+@click.option("--reliability", default=None, help="primary | secondary | tertiary.")
+@click.option("--effective-date", default=None, help="ISO8601 date.")
+@click.option("--retrieved-at", default=None, help="ISO8601 date.")
+@click.option(
+    "--item-refs", "item_refs", default=None,
+    help="Comma-separated item ids this evidence bears on. Anchoring it here "
+    "is what lets `reasoning impact` reach the evidence when one of those "
+    "items moves; `update-evidence` can retrofit it later.",
+)
+@click.option(
+    "--status-ref", "status_ref", default=None,
+    help="Model Status dimension id (e.g. actual / projected) the evidence "
+    "speaks to.",
+)
+@_coverage_anchor_options
+@pass_ctx
+def reasoning_add_evidence_cmd(
+    ctx: Ctx,
+    filename: str,
+    evidence_id: str,
+    source_ref: str,
+    excerpt: str | None,
+    excerpt_file: str | None,
+    at: str | None,
+    reliability: str | None,
+    effective_date: str | None,
+    retrieved_at: str | None,
+    item_refs: str | None,
+    status_ref: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+) -> None:
+    """Add a new <Evidence> to FILENAME's <Reasoning> section."""
+    excerpt = _resolve_text_option(excerpt, excerpt_file, "excerpt")
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    payload = {
+        k: v for k, v in {
+            "id": evidence_id,
+            "sourceRef": source_ref,
+            "excerpt_text": excerpt,
+            "at": at,
+            "reliability": reliability,
+            "effectiveDate": effective_date,
+            "retrievedAt": retrieved_at,
+            "itemRefs": item_refs,
+            "statusRef": status_ref,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+        }.items() if v is not None
+    }
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={"xml": xml, "op": "add_evidence", "payload": payload},
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("set-conclusion", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("claim_id", required=False)
+@click.option(
+    "--clear",
+    is_flag=True,
+    default=False,
+    help="Remove the declaration and fall back to deriving the apex from the "
+    "argument topology.",
+)
+@pass_ctx
+def reasoning_set_conclusion_cmd(
+    ctx: Ctx,
+    filename: str,
+    claim_id: str | None,
+    clear: bool,
+) -> None:
+    """Declare which Claim is FILENAME's main conclusion.
+
+    Writes `<Reasoning conclusionRef="CLAIM_ID">`. Readers open the document on
+    that Claim instead of guessing at the apex from the argument graph — which
+    is wrong whenever a document chains its claims chronologically, because a
+    `depends_on` edge to last week's claim is structurally identical to
+    subordination.
+
+    This does not create a Claim. Author the apex `thesis` with `add-claim`
+    first, then point the section at it.
+
+    Pass `--clear` to remove the declaration.
+    """
+    if clear and claim_id:
+        raise click.UsageError("pass either CLAIM_ID or --clear, not both")
+    if not clear and not claim_id:
+        raise click.UsageError("CLAIM_ID is required (or pass --clear)")
+
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={
+            "xml": xml,
+            "op": "set_conclusion",
+            "target_id": claim_id,
+            "clear": clear,
+        },
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("set-key-question", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("claim_id", required=False)
+@click.option(
+    "--clear",
+    is_flag=True,
+    default=False,
+    help="Remove the declaration. The header then falls back to the `answers` "
+    "edge off the conclusion, then to the document's only question, and "
+    "otherwise shows nothing.",
+)
+@click.option(
+    "--needs-review",
+    "needs_review",
+    is_flag=True,
+    default=False,
+    help="Mark the question as inferred rather than stated, so it renders as "
+    "provisional until someone confirms it. Declaring without this flag "
+    "clears it.",
+)
+@pass_ctx
+def reasoning_set_key_question_cmd(
+    ctx: Ctx,
+    filename: str,
+    claim_id: str | None,
+    clear: bool,
+    needs_review: bool,
+) -> None:
+    """Declare which question FILENAME exists to answer.
+
+    Writes `<Reasoning keyQuestionRef="CLAIM_ID">`. Readers show that question
+    in the Reasoning header instead of taking whichever `kind="question"` Claim
+    happens to be authored first — which meant reordering, importing or
+    deleting a question silently changed what the document appeared to be
+    asking, in 15 of this repo's 34 reasoning-bearing documents.
+
+    This does not create a Claim. Author it with `add-claim --kind question`
+    first, then point the section at it, and record the pairing with
+    `add-argument --from-id <conclusion> --rel answers --to-id CLAIM_ID`.
+
+    Pass `--clear` to remove the declaration.
+    """
+    if clear and claim_id:
+        raise click.UsageError("pass either CLAIM_ID or --clear, not both")
+    if not clear and not claim_id:
+        raise click.UsageError("CLAIM_ID is required (or pass --clear)")
+    if clear and needs_review:
+        raise click.UsageError("--needs-review makes no sense with --clear")
+
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={
+            "xml": xml,
+            "op": "set_key_question",
+            "target_id": claim_id,
+            "clear": clear,
+            "needs_review": needs_review,
+        },
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("set-exhibit", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("exhibit_ref", required=False)
+@click.option(
+    "--clear",
+    is_flag=True,
+    default=False,
+    help="Remove the declaration. The conclusion then renders full width.",
+)
+@pass_ctx
+def reasoning_set_exhibit_cmd(
+    ctx: Ctx,
+    filename: str,
+    exhibit_ref: str | None,
+    clear: bool,
+) -> None:
+    """Declare which deck or slide to show beside FILENAME's conclusion.
+
+    Writes `<Reasoning exhibitRef="EXHIBIT_REF">`, where EXHIBIT_REF is a
+    `deepcell:` URI — `deepcell:deck/executive` or
+    `deepcell:slide/executive.overview`.
+
+    A URI rather than a bare id, unlike its `set-conclusion` and
+    `set-key-question` neighbours: those name Claims inside `<Reasoning>`, and
+    this one points at another surface.
+
+    Optional, and it degrades. No deck in the file means no slot; a reference
+    that does not resolve renders the conclusion full width and lints, because
+    a broken link never breaks a render.
+
+    Pass `--clear` to remove the declaration.
+    """
+    if clear and exhibit_ref:
+        raise click.UsageError("pass either EXHIBIT_REF or --clear, not both")
+    if not clear and not exhibit_ref:
+        raise click.UsageError("EXHIBIT_REF is required (or pass --clear)")
+
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={
+            "xml": xml,
+            "op": "set_exhibit",
+            "exhibit_ref": exhibit_ref,
+            "clear": clear,
+        },
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+#: Built from the Choice so the sentence can never list fewer rels than the
+#: flag accepts — it did, and `answers` was the one it left out.
+_ADD_ARGUMENT_HELP = (
+    "Add a new <Argument> edge to FILENAME's <Reasoning> section.\n\n"
+    "`--from-id` and `--to-id` are required; `--rel` picks the edge type ("
+    + ", ".join(_ARGUMENT_RELS)
+    + ")."
+)
+
+
+@reasoning.command("add-argument", cls=WriteCommand, help=_ADD_ARGUMENT_HELP)
+@click.argument("filename")
+@click.option("--from-id", "from_id", required=True, help="Source node id.")
+@click.option("--to-id", "to_id", required=True, help="Target node id.")
+@click.option(
+    "--rel",
+    required=True,
+    type=click.Choice(_ARGUMENT_RELS),
+    help="How --from-id relates to --to-id: supports / refutes (evidential), "
+    "depends_on (falsifying the target falsifies the source), derives_from "
+    "(computed or inferred from it), answers (this conclusion settles that "
+    "question), variant_of (your view vs a consensus claim), supersedes "
+    "(replaces an older node), contradicts, references. "
+    "See `deepcell ref rel`.",
+)
+@click.option("--id", "arg_id", default=None, help="Argument id (auto-generated if omitted).")
+@click.option(
+    "--weight",
+    default=None,
+    type=float,
+    help="How much this edge carries, 0-1 (optional).",
+)
+@click.option("--body", default=None, help="<Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("<Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option("--status", default=None, help="Argument lifecycle status (active/superseded/revoked).")
+@pass_ctx
+def reasoning_add_argument_cmd(
+    ctx: Ctx,
+    filename: str,
+    from_id: str,
+    to_id: str,
+    rel: str,
+    arg_id: str | None,
+    weight: float | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    status: str | None,
+) -> None:
+    # Help text is `_ADD_ARGUMENT_HELP`, generated from `_ARGUMENT_RELS`.
+    body = _resolve_text_option(body, body_file, "body")
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    payload = {
+        k: v for k, v in {
+            "from": from_id,
+            "to": to_id,
+            "rel": rel,
+            "id": arg_id,
+            "weight": weight,
+            "body_text": body,
+            "body_notation": body_notation,
+            "status": status,
+        }.items() if v is not None
+    }
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={"xml": xml, "op": "add_argument", "payload": payload},
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+# ---------------------------------------------------------------------------
+# Supersede + delete + the remaining updates.
+#
+# `deepcell guide revise/reasoning` teaches "never delete, always supersede" and says
+# the supersede op does it mechanically — but no CLI command emitted it, so the
+# workflow the guide prescribes was unreachable from the CLI and from MCP.
+# ---------------------------------------------------------------------------
+
+
+def _supersede(
+    ctx: Ctx, filename: str, op: str, target_id: str, new_node_key: str,
+    new_node: dict[str, Any],
+) -> None:
+    """POST a supersede op: flip the old node to superseded, add the new one,
+    and emit the <Argument rel="supersedes"> edge between them."""
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={"xml": xml, "op": op, "target_id": target_id, new_node_key: new_node},
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+@reasoning.command("supersede-claim", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("claim_id")
+@click.option("--id", "new_id", required=True, help="Id of the replacement Claim.")
+@click.option(
+    "--label", default=None,
+    help=f"<Label> text of the replacement. {_LABEL_HELP}",
+)
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Label>", "label"),
+)
+@click.option("--body", default=None, help="<Body> text of the replacement.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option(
+    "--kind",
+    default=None,
+    type=click.Choice(_CLAIM_KINDS),
+    help="Kind of the replacement (defaults to the superseded claim's kind).",
+)
+@click.option("--item-refs", "item_refs", default=None, help="Comma-separated item ids.")
+@click.option("--context-refs", "context_refs", default=None, help="Comma-separated context ids.")
+@click.option("--status-ref", "status_ref", default=None, help="Model Status dimension id.")
+@click.option("--calc-ref", "calc_ref", default=None, help="CalcDef id this claim is anchored to.")
+@click.option(
+    "--confidence", default=None, type=float, help="Confidence in the replacement, 0-1."
+)
+@click.option(
+    "--strength", default=None, type=click.Choice(_CLAIM_STRENGTHS),
+    help="How strongly the replacement is held, qualitatively. Not inherited "
+    "from the superseded claim: a reassessment that reused the old strength "
+    "would publish a judgement nobody made.",
+)
+@_narrow_anchor_options
+@pass_ctx
+def reasoning_supersede_claim_cmd(
+    ctx: Ctx,
+    filename: str,
+    claim_id: str,
+    new_id: str,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    kind: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    status_ref: str | None,
+    calc_ref: str | None,
+    confidence: float | None,
+    strength: str | None,
+) -> None:
+    """Replace CLAIM_ID with a new Claim, keeping the old one as history.
+
+    This is the canonical way to change what a Claim asserts — a Claim is a
+    dated position, and rewriting one in place destroys the record of what
+    was believed when. In one atomic edit it flips CLAIM_ID's status to
+    `superseded`, adds the new Claim, and links them with
+    `<Argument rel="supersedes">`, so `deepcell claim history` can walk back.
+
+    The replacement INHERITS the old claim's anchors (--item-refs,
+    --context-refs, --status-ref, --calc-ref, and scenario / custom
+    dimensions) for any you do not pass; passing one overrides it.
+
+    Supersession does not move Arguments that touch the old Claim or the
+    document's conclusionRef. After reassessment, add current edges to the
+    replacement and run `reasoning set-conclusion` if the old Claim was the
+    declared conclusion. See `deepcell guide revise/premise-change`.
+
+    \b
+      deepcell reasoning supersede-claim model.deepcell t_margin_v1 \\
+          --id t_margin_v2 --label "Gross margin reaches 72% by 2027"
+    """
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label", required=True)
+    body = _resolve_text_option(body, body_file, "body")
+    new_claim = {
+        k: v for k, v in {
+            "id": new_id,
+            "kind": kind,
+            "label_text": label,
+            "body_text": body,
+            "body_notation": body_notation,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "statusRef": status_ref,
+            "calcRef": calc_ref,
+            "confidence": confidence,
+            "strength": strength,
+        }.items() if v is not None
+    }
+    _supersede(ctx, filename, "supersede_claim", claim_id, "new_claim", new_claim)
+
+
+@reasoning.command("supersede-assumption", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("assumption_id")
+@click.option("--id", "new_id", required=True, help="Id of the replacement Assumption.")
+@click.option(
+    "--label", default=None,
+    help=f"<Label> text of the replacement. {_LABEL_HELP}",
+)
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Label>", "label"),
+)
+@click.option("--body", default=None, help="<Body> text of the replacement.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option("--item-refs", "item_refs", default=None, help="Comma-separated item ids.")
+@click.option("--status-ref", "status_ref", default=None, help="Model Status dimension id.")
+@click.option("--calc-ref", "calc_ref", default=None, help="CalcDef id this assumption drives.")
+@click.option(
+    "--confidence", default=None, type=float, help="Confidence in the replacement, 0-1."
+)
+@click.option(
+    "--status",
+    default=None,
+    type=click.Choice(_ASSUMPTION_STATUSES),
+    help="Lifecycle status of the replacement.",
+)
+@click.option("--verified-at", "verified_at", default=None, help=_VERIFIED_AT_HELP)
+@click.option("--broken-at", "broken_at", default=None, help=_BROKEN_AT_HELP)
+@_coverage_anchor_options
+@pass_ctx
+def reasoning_supersede_assumption_cmd(
+    ctx: Ctx,
+    filename: str,
+    assumption_id: str,
+    new_id: str,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    status_ref: str | None,
+    calc_ref: str | None,
+    confidence: float | None,
+    status: str | None,
+    verified_at: str | None,
+    broken_at: str | None,
+) -> None:
+    """Replace ASSUMPTION_ID with a new Assumption, keeping the old as history.
+
+    Same mechanics as `supersede-claim`: the old node's status becomes
+    `superseded`, the new node is added, and a `supersedes` Argument links
+    them. Every Claim that depended on the old assumption keeps its edge, so
+    `deepcell assumption impact` still answers for the superseded node.
+
+    Supersession does not attach those Claims to the replacement. After
+    reassessing each surviving Claim, add a new `depends_on` Argument to the
+    replacement and keep the old edge as history. See
+    `deepcell guide revise/premise-change`.
+
+    `--verified-at` / `--broken-at` land on the replacement in the same
+    commit, so recording that the new premise was checked does not take a
+    second `update-assumption`.
+    """
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label", required=True)
+    body = _resolve_text_option(body, body_file, "body")
+    new_assumption = {
+        k: v for k, v in {
+            "id": new_id,
+            "label_text": label,
+            "body_text": body,
+            "body_notation": body_notation,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+            "statusRef": status_ref,
+            "calcRef": calc_ref,
+            "confidence": confidence,
+            "status": status,
+            "verifiedAt": verified_at,
+            "brokenAt": broken_at,
+        }.items() if v is not None
+    }
+    _supersede(
+        ctx, filename, "supersede_assumption", assumption_id,
+        "new_assumption", new_assumption,
+    )
+
+
+_CASCADE_HELP = (
+    "Also remove every Argument touching the node (default). --no-cascade "
+    "keeps them, and is refused with code=would_dangle unless you also pass "
+    "--allow-dangling — a dangling edge lints, and is still addressable by "
+    "its (from, rel, to) or its id, so it can be cleaned up later."
+)
+
+
+def _delete_reasoning_node(
+    ctx: Ctx, filename: str, op: str, target_id: str | None,
+    cascade: bool, allow_dangling: bool, address: dict | None = None,
+) -> None:
+    xml, revision = _get_xml_with_revision(ctx, filename)
+    data = ctx.client.post(
+        "/reasoning/edit",
+        json={
+            "xml": xml, "op": op, "target_id": target_id,
+            "cascade": cascade, "allow_dangling": allow_dangling,
+            **(address or {}),
+        },
+    )
+    _persist_edit_result(ctx, filename, data, revision)
+
+
+def _edge_address(
+    argument_id: str | None, from_id: str | None, edge_rel: str | None,
+    to_id: str | None,
+) -> dict | None:
+    """The triple to send beside `target_id`, or a usage error.
+
+    Both addresses at once is not refused: they may disagree, and the backend
+    resolves `target_id` first, so the triple would be ignored silently. Say
+    so instead.
+    """
+    given = [v for v in (from_id, edge_rel, to_id) if v is not None]
+    if argument_id and given:
+        raise click.UsageError(
+            "Give ARGUMENT_ID or the --from-id/--edge-rel/--to-id triple, not "
+            "both — the id wins and the triple would be ignored."
+        )
+    if not argument_id and len(given) != 3:
+        raise click.UsageError(
+            "Name the edge: either ARGUMENT_ID, or all three of --from-id, "
+            "--edge-rel and --to-id."
+        )
+    if not given:
+        return None
+    return {"from_id": from_id, "edge_rel": edge_rel, "to_id": to_id}
+
+
+def _delete_command(name: str, op: str, noun: str, guidance: str):
+    """Build one `reasoning delete-<noun>` command — the four differ only in
+    the op name and the wording, so the wiring is shared.
+
+    `help=` is passed to the decorator rather than set as `__doc__`
+    afterwards: Click reads the docstring when the command is constructed, so
+    a later assignment leaves the command with no help at all.
+    """
+    @reasoning.command(
+        name,
+        cls=FileFirstWriteCommand,
+        help=(
+            f"Delete the {noun} NODE_ID from FILENAME's <Reasoning> section."
+            f"\n\n{guidance}"
+        ),
+    )
+    @click.argument("filename")
+    @click.argument("node_id")
+    @click.option("--cascade/--no-cascade", default=True, help=_CASCADE_HELP)
+    @click.option(
+        "--allow-dangling",
+        "allow_dangling",
+        is_flag=True,
+        default=False,
+        help="With --no-cascade, permit the delete even though it orphans Arguments.",
+    )
+    @pass_ctx
+    def _cmd(
+        ctx: Ctx, filename: str, node_id: str, cascade: bool, allow_dangling: bool
+    ) -> None:
+        _delete_reasoning_node(ctx, filename, op, node_id, cascade, allow_dangling)
+
+    return _cmd
+
+
+reasoning_delete_claim_cmd = _delete_command(
+    "delete-claim", "delete_claim", "<Claim>",
+    "Prefer `deepcell reasoning supersede-claim`: a Claim is a dated "
+    "position, and deleting one erases the record that it was ever held. "
+    "Delete is for claims authored in error, not for claims that turned "
+    "out wrong — mark those falsified with `update-claim --status "
+    "falsified`.",
+)
+reasoning_delete_assumption_cmd = _delete_command(
+    "delete-assumption", "delete_assumption", "<Assumption>",
+    "Prefer `deepcell reasoning supersede-assumption`. Check what depends "
+    "on it first with `deepcell assumption impact`.",
+)
+reasoning_delete_evidence_cmd = _delete_command(
+    "delete-evidence", "delete_evidence", "<Evidence>",
+    "Removes the cited support itself, so any Claim that rested on it is "
+    "left asserting the same thing with less behind it.",
+)
+
+
+@reasoning.command("delete-argument", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("argument_id", required=False)
+@click.option("--from-id", "from_id", default=None, help="Address: the edge's @from.")
+@click.option(
+    "--edge-rel", "edge_rel", default=None, type=click.Choice(_ARGUMENT_RELS),
+    help="Address: the edge's @rel.",
+)
+@click.option("--to-id", "to_id", default=None, help="Address: the edge's @to.")
+@click.option("--cascade/--no-cascade", default=True, help=_CASCADE_HELP)
+@click.option(
+    "--allow-dangling",
+    "allow_dangling",
+    is_flag=True,
+    default=False,
+    help="With --no-cascade, permit the delete even though it orphans Arguments.",
+)
+@pass_ctx
+def reasoning_delete_argument_cmd(
+    ctx: Ctx,
+    filename: str,
+    argument_id: str | None,
+    from_id: str | None,
+    edge_rel: str | None,
+    to_id: str | None,
+    cascade: bool,
+    allow_dangling: bool,
+) -> None:
+    """Delete one <Argument> edge from FILENAME's <Reasoning> section.
+
+    Removes one edge; both nodes it connected stay. --cascade has no effect
+    here, since an Argument has no inbound edges of its own.
+
+    An Argument has two permanent addresses: its id, which is derived from
+    the edge as arg_{from}__{rel}__{to} and shown by `describe` and the
+    Reasoning panel, and the (from, rel, to) triple it was added with. Give
+    ARGUMENT_ID, or all three of --from-id, --edge-rel and --to-id. Edges
+    written before ids were required have no @id on disk and resolve by
+    either address without the file being rewritten.
+    """
+    address = _edge_address(argument_id, from_id, edge_rel, to_id)
+    _delete_reasoning_node(
+        ctx, filename, "delete_argument", argument_id, cascade, allow_dangling,
+        address=address,
+    )
+
+
+@reasoning.command("update-evidence", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("evidence_id")
+@click.option(
+    "--label", default=None,
+    help=f"Replacement <Label> text. {_LABEL_HELP}",
+)
+@click.option(
+    "--label-file", "label_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Label>", "label"),
+)
+@click.option("--body", default=None, help="Replacement <Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Body>", "body"),
+)
+@click.option("--source", default=None, help="Replacement @source (where the evidence came from).")
+@click.option("--url", default=None, help="Replacement @url.")
+@click.option("--as-of", "as_of", default=None, help="Replacement @asOf date (ISO).")
+@click.option("--item-refs", "item_refs", default=None, help="Comma-separated item ids.")
+@click.option("--context-refs", "context_refs", default=None, help="Comma-separated context ids.")
+@click.option(
+    "--status-ref", "status_ref", default=None,
+    help="Model Status dimension id (e.g. actual / projected) the evidence "
+    "speaks to.",
+)
+@_narrow_anchor_options
+@pass_ctx
+def reasoning_update_evidence_cmd(
+    ctx: Ctx,
+    filename: str,
+    evidence_id: str,
+    label: str | None,
+    label_file: str | None,
+    body: str | None,
+    body_file: str | None,
+    source: str | None,
+    url: str | None,
+    as_of: str | None,
+    item_refs: str | None,
+    context_refs: str | None,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+) -> None:
+    """Patch an <Evidence> node; only the attributes you pass are changed.
+
+    Use it to retrofit anchors onto evidence added before the items existed,
+    or to correct a source URL without losing the Arguments that cite it.
+    """
+    _check_single_stdin(label_file, body_file)
+    label = _resolve_text_option(label, label_file, "label")
+    body = _resolve_text_option(body, body_file, "body")
+    payload = {
+        k: v for k, v in {
+            "label_text": label,
+            "body_text": body,
+            "source": source,
+            "url": url,
+            "asOf": as_of,
+            "itemRefs": item_refs,
+            "contextRefs": context_refs,
+            "statusRef": status_ref,
+            "scenarioRef": scenario_ref,
+            "customDimensions": custom_dimensions,
+        }.items() if v is not None
+    }
+    _update_reasoning_node(ctx, filename, "update_evidence", evidence_id, payload)
+
+
+@reasoning.command("update-argument", cls=FileFirstWriteCommand)
+@click.argument("filename")
+@click.argument("argument_id", required=False)
+@click.option("--from-id", "from_id", default=None, help="Address: the edge's @from.")
+@click.option(
+    "--edge-rel", "edge_rel", default=None, type=click.Choice(_ARGUMENT_RELS),
+    help="Address: the @rel the edge has now. --rel is what to change it to.",
+)
+@click.option("--to-id", "to_id", default=None, help="Address: the edge's @to.")
+@click.option(
+    "--rel",
+    default=None,
+    type=click.Choice(_ARGUMENT_RELS),
+    help="Reclassify the edge — see `deepcell reasoning add-argument --help`.",
+)
+@click.option("--weight", default=None, type=float, help="How much this edge carries, 0-1.")
+@click.option("--body", default=None, help="Replacement <Body> text.")
+@click.option(
+    "--body-file", "body_file", type=_TEXT_FILE, default=None,
+    help=_text_file_help("replacement <Body>", "body"),
+)
+@click.option(
+    "--body-notation", "body_notation", default=None,
+    type=click.Choice(_BODY_NOTATIONS),
+    help=_BODY_NOTATION_HELP,
+)
+@click.option(
+    "--status",
+    default=None,
+    help="Argument lifecycle status (active / superseded / revoked).",
+)
+@pass_ctx
+def reasoning_update_argument_cmd(
+    ctx: Ctx,
+    filename: str,
+    argument_id: str | None,
+    from_id: str | None,
+    edge_rel: str | None,
+    to_id: str | None,
+    rel: str | None,
+    weight: float | None,
+    body: str | None,
+    body_file: str | None,
+    body_notation: str | None,
+    status: str | None,
+) -> None:
+    """Patch an <Argument> edge; only the attributes you pass are changed.
+
+    An Argument has two permanent addresses: its id, which is derived from
+    the edge as arg_{from}__{rel}__{to} and shown by `describe` and the
+    Reasoning panel, and the (from, rel, to) triple it was added with. Give
+    ARGUMENT_ID, or all three of --from-id, --edge-rel and --to-id. Edges
+    written before ids were required have no @id on disk and resolve by
+    either address without the file being rewritten.
+
+    Reclassifying is --rel; the address is --edge-rel. Recasting a reason
+    as a condition is therefore one command:
+    `--from-id r --edge-rel supports --to-id t --rel depends_on`.
+    """
+    address = _edge_address(argument_id, from_id, edge_rel, to_id)
+    body = _resolve_text_option(body, body_file, "body")
+    payload = {
+        k: v for k, v in {
+            "rel": rel,
+            "weight": weight,
+            "body_text": body,
+            "body_notation": body_notation,
+            "status": status,
+        }.items() if v is not None
+    }
+    _update_reasoning_node(
+        ctx, filename, "update_argument", argument_id, payload, address=address,
+    )