reqctl 0.1.38__py3-none-any.whl

reqctl/cli.py

@@ -0,0 +1,1514 @@
+import argparse
+import contextlib
+import dataclasses
+import importlib.metadata
+import io
+import json
+import os
+import sys
+import threading
+import webbrowser
+from pathlib import Path
+
+from . import baseline as _baseline
+from . import cite
+from . import corpus
+from . import fields as _fields
+from . import graph
+from . import history
+from . import portal as _portal
+from . import resolve as _resolve
+from . import write as _write
+from . import validate as _validate
+from .corpus import ReqctlError
+
+EXIT_OK = 0
+EXIT_INVALID = 1
+
+BETWEEN_ITEMS = "\n\n" + "-" * 60 + "\n\n"
+
+
+def _emit(args, data, text):
+    print(json.dumps(data, indent=2) if args.json else text)
+
+
+def _refuse_invalid(root, said):
+    problems = _validate.run(root)
+    if problems:
+        # @req> REQ-30898926@Vu28eWaG_1mE hjpd4a
+        raise ReqctlError("the corpus does not validate; fix these, "
+                          f"then {said}:\n" + "\n".join(problems))
+
+
+def cmd_new(args):
+    store, _ = corpus.load()
+    item = _write.create(store, args.kind, vars(args))
+    _emit(args, {"uid": item.uid, "path": str(item.path)}, item.uid)
+    return EXIT_OK
+
+
+def cmd_lint(args):
+    store, _ = corpus.load()
+    # @req> REQ-85308584@4lLbQIsexIid sri72v
+    uid, _, _, problems = _write.prepare(store, args.kind, vars(args),
+                                         placeholder="draft")
+    faults = [problem.removeprefix(f"{uid}: ") for problem in problems]
+    if args.json:
+        _emit(args, {"faults": faults}, "")
+    elif faults:
+        print("\n".join(faults), file=sys.stderr)
+    else:
+        print("no faults")
+    return EXIT_INVALID if faults else EXIT_OK
+
+
+def _describe(tree, item):
+    data = corpus.raw(item)
+    uid = str(item.uid)
+    _refuse_broken(uid, data)
+    out = {
+        "uid": uid,
+        "kind": corpus.kind_of(uid, data),
+        "status": data.get("status"),
+        "stamp": corpus.stamp(item),
+        "text": str(data.get("text") or "").strip(),
+    }
+    if corpus.kind_of(uid, data) in ("requirement", "guard"):
+        out.update(
+            references=corpus.references(data),
+            concepts=corpus.concept_references(data),
+            acceptance_criteria=data.get("acceptance_criteria") or [],
+        )
+        if corpus.kind_of(uid, data) == "requirement":
+            out.update(
+                type=data.get("type"),
+                verification=data.get("verification"),
+                priority=data.get("priority"),
+            )
+    elif corpus.kind_of(uid, data) == "term":
+        out.pop("text")
+        fields = corpus.term_fields(data)
+        out.update(
+            term=corpus.term_word(data),
+            aliases=fields.get("aliases") or [],
+            definition=str(fields.get("definition") or "").strip(),
+        )
+        # @req> REQ-22686458@dmNVoBq6qCcv q5tknl
+        out["unclaimed"] = corpus.unclaimed(data)
+    elif corpus.kind_of(uid, data) == "data":
+        out.update(name=data.get("name"), entries=corpus.entries(data) or {})
+        # @req> REQ-32949873@Zm9yVRdGWKOQ 4ffzw2
+        out.update(corpus.held_blocks(tree.root, uid, data))
+    else:
+        out.update(
+            name=data.get("name"),
+            value=_dict_value(data),
+            unit=data.get("unit"),
+            value_type=data.get("value_type"),
+        )
+        described = {key: fields for key, fields
+                     in (corpus.entries(data) or {}).items() if fields}
+        if described:
+            out["entries"] = described
+    if data.get("default") is not None:
+        out["default"] = data.get("default")
+    if data.get("rationale"):
+        out["rationale"] = str(data["rationale"]).strip()
+    return out
+
+
+def _refuse_broken(uid, data):
+    if (corpus.kind_of(uid, data) not in ("requirement", "guard")
+            and corpus.entries(data) is None):
+        # @req> REQ-30898926@Vu28eWaG_1mE zlnal5
+        raise ReqctlError(
+            f"{uid}: has no entries -- `reqctl validate` names the fault; "
+            f"edit {uid}'s file by hand so entries maps each key to its fields"
+        )
+
+
+def _dict_value(data):
+    return sorted(corpus.entries(data) or {})
+
+
+def _criterion(mapping):
+    if not isinstance(mapping, dict):
+        return str(mapping)
+    return (f"given {mapping.get('given')} / when {mapping.get('when')} "
+            f"/ then {mapping.get('then')}")
+
+
+def _shown(data):
+    held = corpus.entries(data) or {}
+    suffix = f" {data.get('unit')}" if data.get("unit") else ""
+    default = data.get("default")
+    return ", ".join(f"{key}{suffix}" + (" (default)" if key == default else "")
+                     for key in held)
+
+
+def _value(value, unit):
+    # @req> REQ-49042671@vhxkl2dsMRfs t3z2ju
+    if isinstance(value, dict):
+        return ", ".join(f"{field}: {held}" for field, held in value.items())
+    suffix = f" {unit}" if unit else ""
+    return ", ".join(f"{member}{suffix}" for member in value)
+
+
+def _named_fields(fields, rest, blocks):
+    steps = rest.split(".")
+    found = corpus.entries(fields) or {}
+    if steps[0] in blocks and len(steps) > 1:
+        found, steps = blocks[steps[0]], steps[1:]
+    for step in steps:
+        if not isinstance(found, dict) or step not in found:
+            return None
+        found = found[step]
+    if len(steps) == 1 and isinstance(found, dict):
+        return dict(found)
+    return {steps[-1]: found}
+
+
+def _parameter_value(fields, named, held):
+    if named is not None:
+        return named
+    if held is not None:
+        return sorted(held)
+    return _dict_value(fields)
+
+
+def _entry_fields(fields):
+    # @req> REQ-73719888@SQkvdemRTgC1 3wgrmj
+    return ", ".join(f"{name}: {corpus.plain(value)}"
+                     for name, value in (fields or {}).items())
+
+
+def _nests(fields):
+    return any(isinstance(value, dict) for value in (fields or {}).values())
+
+
+def _entry_lines(key, fields, depth=0, anchor=None):
+    # @req> REQ-22770949@2z1l08YISr1R cglw6c
+    label = f'<a id="{anchor}"></a>{key}' if anchor else key
+    if depth == 0 and not _nests(fields):
+        shown = _entry_fields(fields)
+        return [f"- {label}" + (f" — {shown}" if shown else "")]
+    # @req+ REQ-18993149@6FrsyHRkHj2O s5nw3l
+    held = [f"{'  ' * depth}- {label}"]
+    for name, value in (fields or {}).items():
+        if isinstance(value, dict):
+            held += _entry_lines(name, value, depth + 1)
+        else:
+            # @req> REQ-73719888@SQkvdemRTgC1 g5txax
+            held.append(f"{'  ' * (depth + 1)}- {name}: {corpus.plain(value)}")
+    return held
+    # @req- s5nw3l
+
+
+def _render(fields, order=None):
+    keys = order or list(fields)
+    width = max((len(k) for k in keys if fields.get(k) is not None), default=0)
+    lines = []
+    # @req> REQ-73719888@SQkvdemRTgC1 li6wlm
+    for key in keys:
+        value = fields.get(key)
+        if value in (None, [], "", {}):
+            continue
+        if isinstance(value, dict):
+            value = "; ".join(
+                f"{name} -- {_entry_fields(held) if isinstance(held, dict) else corpus.plain(held)}"
+                if held else str(name)
+                for name, held in value.items()
+            )
+        if isinstance(value, list):
+            value = ", ".join(_criterion(v) if isinstance(v, dict) else corpus.plain(v)
+                              for v in value)
+        lines.append(f"{key.replace('_', ' '):<{width}}  {corpus.plain(value)}")
+    return "\n".join(lines)
+
+
+def cmd_revise(args):
+    tree, _ = corpus.load()
+    # @req+ REQ-94401451@EZFY5LjHcj9g pc3x5s
+    if len(set(args.uid)) > 1:
+        changes = _write.revise_together(tree, args.uid, vars(args))
+        _emit(args, {"changed": changes},
+              "\n".join(f"{uid}: " + (", ".join(sorted(changed)) or "already held")
+                        for uid, changed in changes.items())
+              + "\n  proposed as approved -- approved when this merges to main")
+        return EXIT_OK
+    args.uid = args.uid[0]
+    # @req- pc3x5s
+    changed = _write.revise(tree, args.uid, vars(args))
+    if not changed:
+        _emit(args, {"uid": args.uid, "changed": {}, "already_held": True},
+              f"{args.uid}: already holds everything passed; nothing written")
+        return EXIT_OK
+    note = ""
+    if changed.get("status") == "approved":
+        note = "\n  proposed as approved -- it is approved when this merges to main"
+    spread = changed.get("reworded")
+    if spread:
+        note += (f"\n  reworded {spread['links']} link(s) across "
+                 f"{len(spread['items'])} item(s)")
+        for held in spread["articles"]:
+            note += f"\n    article: {held}"
+        if spread["left"]:
+            note += ("\n  still showing another word, yours to reword or leave: "
+                     + ", ".join(spread["left"]))
+    _emit(
+        args,
+        {"uid": args.uid, "changed": changed},
+        f"{args.uid}: " + ", ".join(sorted(changed)) + note,
+    )
+    return EXIT_OK
+
+
+def cmd_relate(args):
+    tree, _ = corpus.load()
+    repinned = _write.relate(tree, args.source, args.relation, args.target)
+    note = (
+        ": re-pinned to the target's current state"
+        if repinned
+        else "\n  unassessed -- reread both, then run the same relate to pin it"
+    )
+    _emit(
+        args,
+        {"source": args.source, "relation": args.relation, "target": args.target,
+         "repinned": repinned},
+        f"{args.source} {args.relation} {args.target}" + note,
+    )
+    return EXIT_OK
+
+
+def cmd_repin_links(args):
+    tree, _ = corpus.load()
+    repinned = _write.repin_links(tree, args.uids, args.all)
+    _emit(args, repinned,
+          "\n".join(f"{uid}: re-pinned {', '.join(addresses)}"
+                    for uid, addresses in repinned.items())
+          or "nothing to re-pin; nothing was written")
+    return EXIT_OK
+
+
+def cmd_unrelate(args):
+    tree, _ = corpus.load()
+    removed = _write.unrelate(tree, args.source, args.target)
+    _emit(args, {"source": args.source, "target": args.target,
+                 "removed": removed},
+          f"{args.source} no longer links to {args.target}"
+          + ("" if removed else " (it already did not)"))
+    return EXIT_OK
+
+
+def cmd_delete(args):
+    tree, root = corpus.load()
+    # @req> REQ-85755152@bVyS0LwfT-4B xuxjui
+    corpus.find(tree, args.uid)
+    # @req> REQ-43148967@9kz9xDxvdKH5 nghnwd
+    _refuse_invalid(root, "remove")
+    where = _write.delete(tree, args.uid)
+    _emit(args, {"uid": args.uid, "path": str(where)},
+          f"{args.uid} removed. The baseline the default branch carries did "
+          "not state it, so nothing it said is taken back.")
+    return EXIT_OK
+
+
+def cmd_rename(args):
+    tree, root = corpus.load()
+    # @req+ REQ-70208796@rx8OkxlDOpk4 cgdwfu
+    item = corpus.find(tree, args.uid)
+    olds = {item.uid, corpus.name_of(item.uid, item.data)} - {None}
+    cited = [citation for citation in cite.every(root)
+             if citation["uid"] in olds]
+    moved = _write.rename(tree, args.uid, args.name)
+    for citation in cited:
+        corpus.atomic_write(*cite.renamed(root, citation, args.name))
+    # @req- cgdwfu
+    _emit(args, {"uid": args.uid, "name": args.name, "moved": moved},
+          f"{args.uid} answers to {args.name}. "
+          f"{len(moved)} item(s) now address it by that name.")
+    return EXIT_OK
+
+
+def cmd_refile(args):
+    tree, _ = corpus.load()
+    if args.into:
+        address, moved = _write.refile_into(tree, args.uid, *args.into)
+        _emit(args, {"uid": args.uid, "address": address, "moved": moved},
+              f"{args.uid} is filed as {address} and deprecated. "
+              f"{len(moved)} item(s) now reference {address}.")
+        return EXIT_OK
+    repinned = _write.refile(tree, args.uid)
+    _emit(args, {"uid": args.uid, "kind": "data", "repinned": repinned},
+          f"{args.uid} is filed as a data item. "
+          f"{len(repinned)} item(s) had a pin to it refreshed.")
+    return EXIT_OK
+
+
+def _resolved(text, store):
+    # @req+ REQ-70783238@_ngMgAcYCcxF lxx4c3
+    # @req> REQ-68562495@YhDgLuskl6yq i2bing
+    def parameter(match):
+        try:
+            item = corpus.find(store, match.group(1))
+        except ReqctlError:
+            return match.group(0)
+        fields = item.data
+        held = corpus.entries(fields)
+        if held is None:
+            return match.group(0)
+        unit = fields.get("unit")
+        rest = match.group(2)[1:] if match.group(2) else None
+        if rest is None:
+            shown = _shown(fields)
+        elif rest == "default":
+            member = fields.get("default")
+            if member is None:
+                return match.group(0)
+            shown = f"{member} {unit}" if unit else str(member)
+        else:
+            entry, _, field = rest.partition(".")
+            # @req+ REQ-11930677@dH7Pu7k4K4YI ne5nva
+            block = corpus.held_blocks(store.root, item.uid, fields).get(entry)
+            if block is not None:
+                held, unit = block, None
+                entry, _, field = field.partition(".")
+            # @req- ne5nva
+            if entry not in held:
+                return match.group(0)
+            if field:
+                value = (held[entry] if isinstance(held[entry], dict) else {}).get(field)
+                if isinstance(value, list):
+                    value = _value(value, None) or None
+                if value is None:
+                    return match.group(0)
+                shown = field if isinstance(value, dict) else str(value)
+            else:
+                # @req+ REQ-62905646@_RkSNpGGoJXv cs3jo4
+                stated = (block or corpus.cited_entries(item)).get(entry)
+                if (isinstance(stated, dict) and "value_type" in stated
+                        and "quantity" in stated and _write.typed(store)):
+                    shown = _value([stated["quantity"]], stated.get("unit"))
+                else:
+                    shown = f"{entry} {unit}" if unit else entry
+                # @req- cs3jo4
+        return f"[**{shown}**](#{item.uid})"
+    # @req- lxx4c3
+
+    # @req> REQ-73719888@SQkvdemRTgC1 5ubj6l
+    def term(match):
+        uid, rest = corpus.split_address(match.group(2))
+        # @req+ REQ-13364391@mP1skaGV3Fbm o72rua
+        try:
+            found = corpus.find(store, uid)
+        except ReqctlError:
+            return match.group(0)
+        # @req- o72rua
+        if rest is None:
+            return f"[{match.group(1)}](#{found.uid})"
+        # @req> REQ-13364391@mP1skaGV3Fbm fgekao
+        if corpus.concept_at(store.root, found.uid, found.data, rest) is None:
+            return match.group(0)
+        # @req> REQ-22770949@2z1l08YISr1R 54eioc
+        return f"[{match.group(1)}](#{found.uid}.{rest})"
+
+    text = corpus.PARAM_REF.sub(parameter, " ".join(str(text or "").split()))
+    return corpus.CONCEPT_LINK.sub(term, text)
+
+
+def cmd_export(args):
+    tree, root = corpus.load()
+    wanted = None if args.all else "approved"
+    past = history.History(root)
+    if args.json:
+        held = {str(item.uid): dict(corpus.raw(item))
+                for item in corpus.items(tree)}
+        # @req> REQ-82027237@R-XinrGfTNzL ntmmgk
+        print(json.dumps({uid: {**data, "last_updated": past.updated(uid, data)}
+                          for uid, data in sorted(held.items())
+                          if not wanted or data.get("status") == wanted},
+                         indent=2, default=str))
+        return EXIT_OK
+
+    lines = ["# requirements", ""]
+    if wanted:
+        lines += ["Approved requirements only. Use these when judging whether a new",
+                  "idea is already covered, contradicts something, or belongs beside", "one of them.", ""]
+    used_by = {}
+    for item in corpus.items(tree):
+        for address in corpus.concept_references(corpus.raw(item)):
+            target, _ = corpus.split_address(address)
+            try:
+                target = corpus.find(tree, target).uid
+            except ReqctlError:
+                pass
+            used_by.setdefault(target, []).append(str(item.uid))
+
+    count = 0
+    for item in corpus.items(tree):
+        stored = corpus.raw(item)
+        if wanted and stored.get("status") != wanted:
+            continue
+        count += 1
+        uid = str(item.uid)
+        _refuse_broken(uid, stored)
+        # @req+ REQ-59874866@fH6bFHN-Lwa8 6drjr2
+        try:
+            declared = set(_validate.prose_paths(root, uid, stored))
+        except ReqctlError as unreadable:
+            # @req> REQ-30898926@Vu28eWaG_1mE 5djpyt
+            raise ReqctlError(f"{uid}: {unreadable}") from unreadable
+        data = corpus.prosed(stored, declared,
+                             lambda text: _resolved(text, tree))
+        # @req- 6drjr2
+        lines.append(f'<a id="{uid}"></a>')
+        lines.append(f"## {uid}")
+        # @req> REQ-59306961@EGz7Ll3e9FKA dtr4za
+        # @req> REQ-82027237@R-XinrGfTNzL 3adxsp
+        lines.append(f"- last updated: {past.updated(uid, stored) or 'unknown'}")
+        # @req> REQ-22770949@2z1l08YISr1R okkskg
+        marks = "".join(f'<a id="{uid}.{key}"></a>'
+                        for key in corpus.entries(data) or {}
+                        if corpus.DATA_KEY.match(str(key)))
+        if corpus.kind_of(uid, data) == "term":
+            fields = corpus.term_fields(data)
+            # @req> REQ-22770949@2z1l08YISr1R nnfbvp
+            lines.append(f"{marks}**{corpus.term_word(data)}** — "
+                         f"{' '.join(str(fields.get('definition') or '').split())}")
+            aliases = fields.get("aliases") or []
+            if aliases:
+                lines.append(f"- also: {', '.join(str(a) for a in aliases)}")
+            # @req+ REQ-18993149@6FrsyHRkHj2O yxze4j
+            unclaimed = corpus.unclaimed(data)
+            if unclaimed:
+                lines.append("- unclaimed")
+                lines += [f"  - {phrase}: {reason}"
+                          for phrase, reason in unclaimed.items()]
+            # @req- yxze4j
+            lines.append(f"- status: {data.get('status')}")
+            users = sorted(used_by.get(uid, ()))
+            if users:
+                lines.append("- used by: "
+                             + ", ".join(f"[{u}](#{u})" for u in users))
+            lines.append("")
+            continue
+        if corpus.kind_of(uid, data) in ("requirement", "guard"):
+            lines.append(str(data.get("text") or ""))
+            lines.append("")
+            lines.append(f"- status: {data.get('status')}")
+            if corpus.kind_of(uid, data) == "requirement":
+                lines.append(
+                    f"- type: {data.get('type')} · verification: "
+                    f"{data.get('verification')} · priority: {data.get('priority')}")
+            for target, relation in sorted(corpus.mapping(data, "relations").items()):
+                lines.append(f"- {relation} {target}")
+            for criterion in data.get("acceptance_criteria") or []:
+                lines.append(f"- {_criterion(criterion)}")
+        elif corpus.kind_of(uid, data) == "data":
+            lines.append(f"`{data.get('name')}`")
+            if data.get("text"):
+                lines.append(str(data.get("text")))
+            for key, fields in (corpus.entries(data) or {}).items():
+                # @req> REQ-22770949@2z1l08YISr1R qc2ek5
+                lines += _entry_lines(key, fields, anchor=f"{uid}.{key}")
+            # @req> REQ-32949873@Zm9yVRdGWKOQ iwaspp
+            for block, held in corpus.held_blocks(root, uid, data).items():
+                lines.append(f"- {block}")
+                for member, fields in held.items():
+                    lines += (_entry_lines(member, fields, 1, f"{uid}.{block}.{member}")
+                              if isinstance(fields, dict)
+                              else [f"  - {member}: {corpus.plain(fields)}"])
+            lines.append(f"- status: {data.get('status')}")
+        else:
+            # @req> REQ-22770949@2z1l08YISr1R adyi2v
+            lines.append(f"{marks}{str(data.get('text') or '')} "
+                         f"**{_shown(data)}** "
+                         f"(`{data.get('name')}`)")
+            for key, fields in (corpus.entries(data) or {}).items():
+                if fields:
+                    lines += _entry_lines(key, fields)
+            lines.append(f"- status: {data.get('status')}")
+        if data.get("rationale"):
+            lines.append(f"- rationale: {data['rationale']}")
+        lines.append("")
+
+    if not count:
+        lines.append("_Nothing approved yet._")
+    print("\n".join(lines))
+    return EXIT_OK
+
+
+def _behind(row, data):
+    if row is None:
+        return ""
+    # @req> REQ-24608716@rrTjNN2Ay0D0 4lmsbv
+    if row["pinned"]:
+        return (f"   SUSPECT -- pinned @{row['pinned']}, now @{row['held']}"
+                + history.lines(row))
+    return "   SUSPECT -- no stamp; cite it again with reqctl tag"
+
+
+# @req> REQ-24608716@rrTjNN2Ay0D0 o2outx
+def _pins(store, past, binder, addresses):
+    # @req> REQ-81493991@71cbxqAtqZTk dqf5kb
+    if binder.data.get("status") in _validate.RETIRED:
+        return {"suspect": False, "pins": []}
+    pins = corpus.mapping(binder.data, "assessed")
+    held = [{"address": address, "pinned": pins.get(address),
+             **past.pinned(bound.uid, bound.data, rest, pins.get(address))}
+            for address in addresses if corpus.is_suspect(store, binder, address)
+            for target, rest in [corpus.split_address(address)]
+            for bound in [corpus.find(store, target)]]
+    return {"suspect": bool(held), "pins": held}
+
+
+# @req> REQ-24608716@rrTjNN2Ay0D0 3c5yr2
+def _shown_pins(row):
+    return "".join(history.lines(pin) for pin in row.get("pins", ()))
+
+
+def _context(store, item, dependents, tags, past):
+    uid = item.uid
+    kinds = corpus.mapping(item.data, "relations")
+    pins = corpus.mapping(item.data, "assessed")
+
+    outgoing = []
+    for target in sorted(kinds):
+        entry = {
+            "target": target,
+            "relation": kinds.get(target),
+            "assessed_against": pins.get(target),
+        }
+        try:
+            corpus.find(store, target)
+        except ReqctlError:
+            entry.update(suspect=True, missing=True)
+        else:
+            entry.update(missing=False, **_pins(store, past, item, [target]))
+        outgoing.append(entry)
+
+    incoming = [
+        {
+            "source": other.uid,
+            "relation": corpus.mapping(other.data, "relations").get(uid)
+            or "references",
+            **_pins(store, past, other, [uid]),
+        }
+        for other in dependents.get(uid, ()) if other.uid != uid
+    ]
+
+    lookup = corpus.data_lookup(store)
+    parameters = []
+    for address in corpus.references(item.data):
+        target, rest = corpus.split_address(address)
+        entry = {"uid": address, "assessed_against": pins.get(address)}
+        try:
+            fields = corpus.find(store, target).data
+        except ReqctlError:
+            fields = None
+        # @req+ REQ-49042671@vhxkl2dsMRfs pgeszq
+        held = corpus.flagged(fields, rest) if fields is not None else None
+        addresses_item = rest in (None, "default", corpus.MEMBERS) or held is not None
+        # @req> REQ-11930677@dH7Pu7k4K4YI h6snkl
+        named = (None if fields is None or addresses_item
+                 else _named_fields(fields, rest, corpus.held_blocks(
+                     store.root, target, fields)))
+        if fields is None or (not addresses_item and named is None):
+            entry.update(name=None, value=None, unit=None, status=None,
+                         missing=True, suspect=True)
+        else:
+            entry.update(name=fields.get("name"),
+                         value=_parameter_value(fields, named, held),
+                         unit=fields.get("unit"), status=fields.get("status"),
+                         missing=False, **_pins(store, past, item, sorted(
+                             corpus.expand_address(lookup, address))))
+        # @req- pgeszq
+        parameters.append(entry)
+
+    concepts = []
+    for address in corpus.concept_references(item.data):
+        entry = {"uid": address, "assessed_against": pins.get(address)}
+        target, rest = corpus.split_address(address)
+        try:
+            fields = corpus.find(store, target).data
+        except ReqctlError:
+            fields = None
+        held = corpus.concept_at(store.root, target, fields, rest)
+        if held is None:
+            entry.update(word=None, definition=None, status=None, missing=True,
+                         suspect=True)
+        else:
+            entry.update(word=held[0], definition=held[1],
+                         status=fields.get("status"), missing=False,
+                         **_pins(store, past, item, [address]))
+        concepts.append(entry)
+
+    # @req> REQ-19896380@lvCPXiVYZ6ud 7iy6c4
+    cited = [(path, pinned) for path, pinned, _ in tags.get(uid, [])
+             if not corpus.is_test(path)]
+    references = list(dict.fromkeys(path for path, _ in cited))
+    described = _describe(store, item)
+    # @req> REQ-24608716@rrTjNN2Ay0D0 2texd5
+    behind = {
+        path: {"path": path, "pinned": pinned or None,
+               "held": corpus.tag_stamp(described["stamp"]),
+               **past.cited(uid, item.data, None, pinned or None)}
+        for path, pinned in cited
+        if uid.startswith(("REQ-", "GUARD-"))
+        and pinned != corpus.tag_stamp(described["stamp"])
+    }
+    # @req> REQ-73390844@n9jY7LpISW2S s7yx36
+    # @req> REQ-82027237@R-XinrGfTNzL d3gygm
+    updated = past.updated(uid, item.data)
+    data = {
+        **described,
+        "last_updated": updated,
+        "outgoing": outgoing,
+        "incoming": incoming,
+        "parameters": parameters,
+        "concepts": concepts,
+        "implementation": references,
+        "stale": list(behind.values()),
+        "suspect_links": sum(
+            1 for r in outgoing + parameters + concepts if r["suspect"]
+        ),
+    }
+
+    # @req> REQ-59306961@EGz7Ll3e9FKA yoxktl
+    # @req> REQ-82027237@R-XinrGfTNzL wmao62
+    blocks = [_render({**described, "last_updated": updated or "unknown"})]
+    linked = (
+        ("parameters", "parameter", parameters,
+         lambda r: f"{r['name']} = {_value(r['value'], r['unit'])}"),
+        ("concepts", "concept", concepts,
+         lambda r: f"{r['word']} -- {r['definition']}"),
+    )
+    for label, noun, rows, summary in linked:
+        if rows:
+            blocks.append(
+                f"\n{label}\n"
+                + "\n".join(
+                    f"  {r['uid']}  MISSING -- no such {noun}" if r["missing"]
+                    else f"  {r['uid']}  {summary(r)}"
+                    + (f"   {str(r['status']).upper()} -- not approved"
+                       if r["status"] != "approved" else "")
+                    + ("   SUSPECT -- reread, then revise "
+                       f"{uid} --ack {r['uid']}" if r["suspect"] else "")
+                    + _shown_pins(r)
+                    for r in rows
+                )
+            )
+    if outgoing:
+        blocks.append(
+            "\ndepends on\n"
+            + "\n".join(
+                f"  {r['relation']} {r['target']}"
+                + ("   MISSING -- no such item" if r["missing"]
+                   else "   SUSPECT -- reassess before implementing" if r["suspect"]
+                   else "")
+                + _shown_pins(r)
+                for r in outgoing
+            )
+        )
+    if incoming:
+        blocks.append(
+            "\ndepended on by\n"
+            + "\n".join(
+                f"  {r['source']} {r['relation']}"
+                f"{'   SUSPECT' if r['suspect'] else ''}"
+                + _shown_pins(r)
+                for r in incoming
+            )
+        )
+    blocks.append(
+        "\nimplementation\n"
+        + ("\n".join(f"  {p}{_behind(behind.get(p), data)}"
+                      for p in references) or "  none")
+    )
+    return data, "\n".join(blocks)
+
+
+def cmd_context(args):
+    store, root = corpus.load()
+    # @req> REQ-35805881@37XtC4gyD98k dktwfq
+    tags = cite.cited(cite.readable(root))
+    # @req> REQ-40478019@_dwqsOpSOQXA fgrxuj
+    graph.whole(store, tags)
+    dependents = {}
+    for other in corpus.items(store):
+        for target in {corpus.split_address(a)[0]
+                       for a in corpus.dependencies(other.data)}:
+            dependents.setdefault(target, []).append(other)
+
+    past = history.History(root)
+    rows = []
+    for uid in dict.fromkeys(args.uid):
+        try:
+            rows.append(_context(store, corpus.find(store, uid),
+                                 dependents, tags, past))
+        except ReqctlError as fault:
+            rows.append(({"uid": uid, "error": str(fault)},
+                         _render({"uid": uid, "unreadable": str(fault)})))
+
+    held = [data for data, _ in rows]
+    if all("error" in data for data in held):
+        # @req> REQ-30898926@Vu28eWaG_1mE wo5x6j
+        raise ReqctlError("; ".join(data["error"] for data in held))
+
+    if args.json:
+        _emit(args, held, "")
+        return EXIT_OK
+
+    for data in held:
+        if "error" in data:
+            print(f"reqctl: {data['error']}", file=sys.stderr)
+    print(BETWEEN_ITEMS.join(text for _, text in rows))
+    return EXIT_OK
+
+
+def _handle(uid, data):
+    if corpus.kind_of(uid, data) == "term":
+        fields = corpus.term_fields(data)
+        aliases = ", ".join(str(a) for a in fields.get("aliases") or [])
+        word = corpus.term_word(data) or ""
+        return f"{word} ({aliases})" if aliases else word
+    if corpus.kind_of(uid, data) in ("requirement", "guard"):
+        return " ".join(str(data.get("text") or "").split())
+    return str(data.get("name") or "")
+
+
+def cmd_list(args):
+    store, root = corpus.load()
+    past = history.History(root, [args.kind] if args.kind else corpus.FOLDERS)
+    rows = []
+    for item in corpus.items(store):
+        uid = str(item.uid)
+        data = corpus.raw(item)
+        kind = corpus.kind_of(uid, data)
+        if args.kind and kind != args.kind:
+            continue
+        # @req> REQ-82027237@R-XinrGfTNzL fudp2r
+        rows.append({"uid": uid, "kind": kind, "status": data.get("status"),
+                     "last_updated": past.updated(uid, data),
+                     "handle": _handle(uid, data)})
+    rows.sort(key=lambda r: (r["kind"] or "", r["handle"].lower(), r["uid"]))
+
+    if args.json:
+        _emit(args, {"items": rows}, "")
+        return EXIT_OK
+    if not rows:
+        print("no items" + (f" of kind {args.kind}" if args.kind else ""))
+        return EXIT_OK
+    width = max(len(r["status"] or "") for r in rows)
+    dated = max(len(r["last_updated"] or "unknown") for r in rows)
+    for row in rows:
+        handle = row["handle"]
+        if row["kind"] != "term" and len(handle) > 72:
+            handle = handle[:71] + "…"
+        # @req> REQ-59306961@EGz7Ll3e9FKA 6zyhtu
+        # @req> REQ-82027237@R-XinrGfTNzL e6npos
+        print(f"{row['uid']}  {(row['status'] or ''):<{width}}  "
+              f"{row['last_updated'] or 'unknown':<{dated}}  {handle}")
+    return EXIT_OK
+
+
+def cmd_validate(args):
+    root = corpus.find_root()
+    exempted: list[str] = []
+    problems = _validate.run(root, exempted)
+    count = len(corpus.item_files(root))
+    if args.json:
+        _emit(args, {"valid": not problems, "items": count, "problems": problems,
+                     "unclaimed": exempted}, "")
+        return EXIT_INVALID if problems else EXIT_OK
+    # @req> REQ-88221320@vIuzLHP0hHUo gvnev6
+    # @req+ REQ-46373547@54MxhOaz3t8O qu6gxb
+    if exempted:
+        print("\n".join(exempted) if args.verbose else
+              f"{len(exempted)} occurrence(s) accepted unlinked through a "
+              "recorded phrase; validate --verbose lists them")
+    # @req- qu6gxb
+    if problems:
+        print("\n".join(problems), file=sys.stderr)
+        print(f"\n{len(problems)} problem(s) across {count} item(s)", file=sys.stderr)
+    else:
+        print(f"corpus valid: {count} item(s)")
+    return EXIT_INVALID if problems else EXIT_OK
+
+
+def cmd_trace(args):
+    tree, root = corpus.load()
+    # @req> REQ-27097724@WuK_Hn1OEs1s htlxvr
+    data = graph.trace(tree, root, args.uid, args.base, args.record)
+    if args.json:
+        _emit(args, data, "")
+    else:
+        for row in data["rows"]:
+            print(f"{row['uid']}  {row['status']}")
+            for path in row["implementation"]:
+                print(f"    impl  {path}")
+        # @req> REQ-73027720@2Z15jgYQYfsS iy3utt
+        if data["unimplemented"]:
+            print("\nawaiting implementation: " + ", ".join(data["unimplemented"]))
+        # @req> REQ-35979865@pd7CVJ7isMys wht4dr
+        if data["deprecated"]:
+            print("\ncited though deprecated")
+            for row in data["deprecated"]:
+                print(f"  {row['uid']}  {row['path']}")
+        if data["stale"]:
+            print("\nbehind the corpus", file=sys.stderr)
+            for row in data["stale"]:
+                # @req> REQ-24608716@rrTjNN2Ay0D0 zfc5eh
+                print(f"  {row['uid']}  {row['path']}  "
+                      f"pinned @{row['pinned']}, now @{row['held']}"
+                      + history.lines(row), file=sys.stderr)
+        if data["problems"]:
+            print("\n".join(data["problems"]), file=sys.stderr)
+    return EXIT_INVALID if data["problems"] or data["stale"] else EXIT_OK
+
+
+# @req> REQ-78685242@0TbO1Puhk4VD da5qxm
+def _listed(store, uid, entries):
+    item = corpus.find(store, uid)
+    # @req> REQ-88203622@wlZ9orsr9c7q 3xsagz
+    if not corpus.citable(item):
+        return []
+    before = corpus.mapping(item.data, corpus.CITATION_LIST)
+    held = dict(before)
+    for identity, taken in entries.items():
+        if taken is None:
+            held.pop(identity, None)
+        else:
+            held[identity] = taken
+    if held == before:
+        return []
+    if held:
+        item.data[corpus.CITATION_LIST] = held
+    else:
+        item.data.pop(corpus.CITATION_LIST, None)
+    return [(item.path, corpus.dump(item.data))]
+
+
+# @req> REQ-40478019@_dwqsOpSOQXA pcofn5
+def _whole(tree, root, args):
+    target = Path(args.path).resolve()
+    try:
+        relative = target.relative_to(Path(root).resolve()).as_posix()
+    except ValueError as error:
+        # @req> REQ-30898926@Vu28eWaG_1mE qgpboq
+        raise ReqctlError(f"{args.path}: not in the code base at {root} -- "
+                          "give a path inside it") from error
+    digest = cite.whole(relative, target.read_bytes().decode())
+    asked = list(dict.fromkeys(args.req))
+    changes = {}
+    for req in asked:
+        item, entry = corpus.cited_item(tree, req)
+        if entry or not corpus.citable(item):
+            # @req> REQ-30898926@Vu28eWaG_1mE oiki6a
+            raise ReqctlError(f"{req}: a whole-file citation is held by a requirement, "
+                              "a guard, a parameter or a data item -- name one of "
+                              "those, not an entry of one, with --req")
+        item.data[corpus.WHOLE_FILES] = {
+            **corpus.mapping(item.data, corpus.WHOLE_FILES),
+            relative: {"pinned": corpus.cited_stamp(item),
+                       "digest": digest}}
+        changes[item.path] = corpus.dump(item.data)
+    corpus.write_all(changes.items())
+    _emit(args, {"path": relative, "uids": asked},
+          f"{relative} cited whole for {', '.join(asked)}")
+    return EXIT_OK
+
+
+def cmd_tag(args):
+    tree, root = corpus.load()
+    # @req> REQ-74702510@gU2X5OnlUbY3 hmh22z
+    if args.names:
+        if args.first or args.last:
+            # @req> REQ-30898926@Vu28eWaG_1mE ygm75x
+            raise ReqctlError("give each citation a --name or a --from and --to, not both")
+        spans = [cite.spanned(args.path, name) for name in args.names]
+        args.first, args.last = map(list, zip(*spans))
+    # @req> REQ-40478019@_dwqsOpSOQXA jwvxph
+    if args.first is None and args.last is None:
+        return _whole(tree, root, args)
+    # @req+ REQ-62782894@x4o_oB5H0-tY nmyxfc
+    if not len(args.first or []) == len(args.last or []) == len(args.req):
+        # @req> REQ-30898926@Vu28eWaG_1mE vgjbxe
+        raise ReqctlError("name --from and --to, or --name, and --req once for each citation")
+    asked = []
+    for first, last, req in zip(args.first, args.last, args.req):
+        item, entry = corpus.cited_item(tree, req)
+        # @req> REQ-88203622@wlZ9orsr9c7q myjx5s
+        if not corpus.citable(item):
+            # @req> REQ-30898926@Vu28eWaG_1mE h5bqh2
+            raise ReqctlError(f"{req}: only a requirement, a guard, a parameter, "
+                              "a data item or one entry of a data item is cited "
+                              "-- name one of those with --req")
+        # @req> REQ-22755763@lFaaseccSg81 yiibpx
+        # @req> REQ-34330878@E2ViDxqgA25l nqvtul
+        # @req> REQ-18176935@A6AhLhUZ7MdW wkv6gw
+        asked.append((first, last, f"{item.uid}.{entry}" if entry else str(item.uid),
+                      corpus.cited_stamp(item, entry)))
+    change, written = cite.tagged(root, args.path, asked, args.exclusive)
+    # @req- nmyxfc
+    changes = [change]
+    # @req> REQ-75539229@263gd_-RLfVL c7r3ff
+    # @req> REQ-89706423@fyVHTsenA51D wrzqdw
+    for uid in dict.fromkeys(uid for _, uid, _ in written):
+        changes += _listed(tree, uid, {identity: taken
+                                       for identity, named, taken in written
+                                       if named == uid})
+    # @req> REQ-65668011@WuPZe9UcmiaP 4pj4jj
+    corpus.write_all(changes)
+    identities = [identity for identity, _, _ in written]
+    _emit(args, {"ids": identities, "path": args.path}, "\n".join(identities))
+    return EXIT_OK
+
+
+# @req> REQ-96580262@hSRVhY3ybYl9 r4nj25
+def cmd_repin(args):
+    tree, root = corpus.load()
+    files, listed, rows = {}, {}, []
+    # @req+ REQ-65738797@3jHtqzLVQUal g4qwzc
+    for citation, standing in cite.pinning(root, list(dict.fromkeys(args.id))):
+        # @req> REQ-57688239@Pv7jzOAUDd-O rmkf77
+        item, entry = corpus.cited_item(tree, citation["address"])
+        # @req> REQ-70626698@nJ3cW5CgMJtE s45utm
+        if corpus.raw(item).get("status") == "deprecated":
+            # @req> REQ-30898926@Vu28eWaG_1mE jhlw6y
+            raise ReqctlError(f"{citation['uid']} is deprecated -- a citation of it "
+                              f"is removed, not re-pinned: `reqctl untag {citation['id']}`; "
+                              "nothing was re-pinned")
+        # @req> REQ-57688239@Pv7jzOAUDd-O btnwzg
+        # @req> REQ-41600593@dauTiMee9rmb pu2zgs
+        stamp = corpus.cited_stamp(item, entry)
+        files.setdefault(citation["path"], []).append((citation, stamp))
+        # @req> REQ-64846889@TSG5uy3nM0nk 77re7v
+        listed.setdefault(citation["uid"], {})[citation["id"]] = standing
+        rows.append({"id": citation["id"], "path": citation["path"], "stamp": stamp})
+    # @req+ REQ-17757558@XeiCnIpn4RLV nkxtiu
+    changes = [cite.repinned(root, pins) for pins in files.values()]
+    for uid, entries in listed.items():
+        changes += _listed(tree, uid, entries)
+    # @req- nkxtiu
+    # @req> REQ-65668011@WuPZe9UcmiaP nmk2ra
+    corpus.write_all(changes)
+    # @req- g4qwzc
+    _emit(args, rows[0] if len(rows) == 1 else rows,
+          "\n".join(f"{row['id']} in {row['path']} pinned @{row['stamp']}" for row in rows))
+    return EXIT_OK
+
+
+def _unwhole(tree, root, args):
+    try:
+        relative = Path(args.id).resolve().relative_to(
+            Path(root).resolve()).as_posix()
+    except ValueError as error:
+        # @req> REQ-30898926@Vu28eWaG_1mE 2g2etu
+        raise ReqctlError(f"{args.id}: not in the code base at {root} -- "
+                          "give a path inside it") from error
+    asked = list(dict.fromkeys(args.req))
+    changes = {}
+    for req in asked:
+        item = corpus.find(tree, req)
+        held = corpus.mapping(item.data, corpus.WHOLE_FILES)
+        # @req> REQ-21009265@yuxuTugeVMu5 p3htis
+        if relative not in held:
+            # @req> REQ-30898926@Vu28eWaG_1mE uxrhvu
+            raise ReqctlError(f"{req} holds no whole-file citation of "
+                              f"{relative}; nothing was changed -- "
+                              f"reqctl trace {req} lists what it cites")
+        # @req+ REQ-98709103@JryTDKzxpwrF ckhfaq
+        # @req+ REQ-49367452@tPjE-de7pYv_ m6zfum
+        rest = {path: cited for path, cited in held.items() if path != relative}
+        data = {key: value for key, value in item.data.items()
+                if key != corpus.WHOLE_FILES}
+        if rest:
+            data[corpus.WHOLE_FILES] = rest
+        changes[item.path] = corpus.dump(data)
+        # @req- m6zfum
+        # @req- ckhfaq
+    corpus.write_all(changes.items())
+    _emit(args, {"path": relative, "uids": asked},
+          f"{relative} no longer cited whole by {', '.join(asked)}")
+    return EXIT_OK
+
+
+def cmd_untag(args):
+    tree, root = corpus.load()
+    # @req> REQ-98709103@JryTDKzxpwrF fzxhli
+    if args.req:
+        return _unwhole(tree, root, args)
+    # @req> REQ-51709712@D0x4hZmSHgiW j65lln
+    citation = cite.named(root, args.id, placed=False)
+    changes = [cite.untagged(root, citation)]
+    # @req> REQ-13298390@Pum5hwaVAaJo utmfsc
+    # @req> REQ-81275367@2q0tIHQCM4br olrtj5
+    # @req> REQ-28888702@sxS9aXY0y0Ed iwdu5n
+    if citation["uid"] in {str(item.uid) for item in corpus.items(tree)}:
+        changes += _listed(tree, citation["uid"], {args.id: None})
+    # @req> REQ-65668011@WuPZe9UcmiaP jwd2cj
+    corpus.write_all(changes)
+    _emit(args, {"id": args.id, "path": citation["path"]},
+          f"{args.id} removed from {citation['path']}")
+    return EXIT_OK
+
+
+def cmd_unlist(args):
+    tree, root = corpus.load()
+    item = corpus.find(tree, args.uid)
+    uid = str(item.uid)
+    # @req> REQ-97939970@lyVUGGzeSEQW xrna4u
+    # @req> REQ-44322088@sDoz9XZ22EBj 7e5dqc
+    if (not corpus.citable(item)
+            or args.id not in corpus.mapping(item.data, corpus.CITATION_LIST)):
+        # @req> REQ-30898926@Vu28eWaG_1mE 2x7oac
+        raise ReqctlError(f"{uid}: its citation list does not hold {args.id} -- "
+                          "reqctl trace names the item whose list holds it")
+    # @req+ REQ-59136977@-tsi9nTBSL9- s3g7ya
+    # @req> REQ-81063063@v5hfLK63eQj_ rphl5n
+    # @req> REQ-62685242@nMlCr6nshoNZ cwxoe2
+    if any(citation["uid"] == uid for citation in cite.readable(root, args.id)):
+        # @req> REQ-30898926@Vu28eWaG_1mE pkwvbp
+        raise ReqctlError(
+            f"{uid}: a statement citation names {args.id} -- reqctl untag "
+            f"{args.id} removes the citation, reqctl repin {args.id} re-pins it")
+    # @req> REQ-56797974@xJHqq1DXePrs tn22pk
+    corpus.write_all(_listed(tree, uid, {args.id: None}))
+    # @req- s3g7ya
+    _emit(args, {"uid": uid, "id": args.id},
+          f"{args.id} removed from the citation list of {uid}")
+    return EXIT_OK
+
+
+def cmd_compare(args):
+    root = corpus.find_root()
+    ref = args.base or _baseline._default_ref(root)
+    if ref is None:
+        # @req> REQ-30898926@Vu28eWaG_1mE gl353f
+        raise ReqctlError("no origin to compare against -- name one with --base")
+    data = cite.compare(root, ref)
+    lines = [f"{row['id']}  {row['uid']}  {row['path']}  {', '.join(row['state'])}"
+             for row in data["citations"]]
+    # @req> REQ-33614084@XHPdW0ynnY4c kiiwp5
+    lines += [f"whole  {row['uid']}  {row['path']}  {', '.join(row['state'])}"
+              for row in data["files"]]
+    lines.append("touches: " + (", ".join(data["touches"]) or "nothing"))
+    _emit(args, data, "\n".join(lines))
+    return EXIT_OK
+
+
+# @req> REQ-49576265@pFihs7WdIwGS pihyx4
+def _opened(url):
+    if not webbrowser.open(url):
+        print(f"no browser opened; open {url} in one", file=sys.stderr)
+
+
+def cmd_portal(args):
+    held = _portal.repository(os.getcwd())
+    # @req+ REQ-49576265@pFihs7WdIwGS wx5icq
+    server = _portal.server()
+    # @req> REQ-53764133@s638VvRMfEgi f7ob5l
+    url = f"http://{_portal.HOST}:{_portal.PORT}/?repo={held}"
+    _emit(args, {"repository": held, "url": url},
+          f"the portal on {held} is at {url} -- Ctrl-C stops it")
+    sys.stdout.flush()
+    threading.Thread(target=_opened, args=(url,), daemon=True).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    # @req- wx5icq
+    return EXIT_OK
+
+
+def cmd_resolve(args):
+    store, _ = corpus.load()
+    path, dropped, unlisted = _resolve.resolve(store, args.uid)
+    said = f"{args.uid}: resolved"
+    if dropped:
+        acks = " ".join(f"--ack {gone}" for gone in dropped)
+        said += (f"; the merge conflicted {', '.join(dropped)}, now suspect "
+                 f"-- reread, then reqctl revise {args.uid} {acks}")
+    if unlisted:
+        said += (f"; the merge conflicted citations {', '.join(unlisted)}, now "
+                 f"unlisted -- read each against {args.uid}, then reqctl repin "
+                 "it")
+    _emit(args, {"uid": args.uid, "path": str(path), "dropped": dropped,
+                 "unlisted": unlisted}, said)
+    return EXIT_OK
+
+
+def cmd_baseline(args):
+    tree, root = corpus.load()
+
+    if args.generate:
+        # @req> REQ-64286515@d0Nt8dNubZNP nb26v5
+        _refuse_invalid(root, "generate")
+        number, path, count, claimed = _baseline.generate(tree, root)
+        said = (
+            f"baseline {number} written with {count} approved item(s).\n"
+            "It states what is approved; it does not approve anything."
+        )
+        # @req> REQ-28086776@7S0DPOiDLvSm dlppjs
+        if claimed:
+            stated = " and ".join(str(one) for one in sorted(set(claimed)))
+            said = (
+                f"an unresolved merge claiming {stated} was regenerated rather "
+                "than merged.\n" + said
+            )
+        _emit(
+            args,
+            {"baseline": number, "path": str(path), "items": count,
+             "resolved": claimed},
+            said,
+        )
+        return EXIT_OK
+
+    number, problems = _baseline.check(tree, root)
+    if args.json:
+        _emit(args, {"baseline": number, "valid": not problems, "problems": problems}, "")
+    elif problems:
+        print("\n".join(problems), file=sys.stderr)
+        if number is not None:
+            print(f"\nbaseline {number} does not match the corpus", file=sys.stderr)
+    elif number is None:
+        print("no baseline yet")
+    else:
+        print(f"baseline {number} matches the corpus")
+    return EXIT_INVALID if problems else EXIT_OK
+
+def _command(sub, name, said):
+    return sub.add_parser(name, help=said, description=said)
+
+
+RESERVED = ("json", "command", "func", "uid", "kind")
+FIELDED = ("new", "lint", "revise")
+
+
+def _field_arguments(s, flags, taken=()):
+    for flag in flags:
+        if flag.dest in taken and flag.entries:
+            continue
+        if flag.dest in RESERVED + tuple(taken):
+            # @req> REQ-30898926@Vu28eWaG_1mE 5w6stc
+            raise ReqctlError(f"a kind schema gives a field {flag.flag}, which "
+                              "reqctl takes for its own; mark the field readOnly "
+                              "if tooling writes it, or give it another x-flag")
+        try:
+            if flag.switch:
+                s.add_argument(flag.flag, action="store_true", default=None)
+            else:
+                s.add_argument(flag.flag, choices=list(flag.choices) or None,
+                               action="append" if flag.repeated else "store",
+                               type=flag.convert, metavar=flag.metavar)
+        except argparse.ArgumentError as clash:
+            # @req> REQ-30898926@Vu28eWaG_1mE jvhvno
+            raise ReqctlError(f"a kind schema gives a field {flag.flag}, which "
+                              f"reqctl takes for its own: {clash} -- give the "
+                              "field another x-flag in its kind schema") from None
+
+
+def _item_arguments(s, flags):
+    s.add_argument("kind", choices=list(_write.KINDS))
+    # @req> REQ-71965656@F8ulVugEMpD- f7bkcf
+    _field_arguments(s, flags)
+
+
+def _fielded(argv):
+    return next((token for token in argv if not token.startswith("-")),
+                None) in FIELDED
+
+
+def _value_typed(root, flags):
+    # @req+ REQ-58926409@zt0Kl436tNXd 54mksz
+    store, _ = corpus.load(root)
+    corpus.items(store)
+    try:
+        listed = corpus.find(store, _validate.VALUE_TYPES)
+    except ReqctlError:
+        return flags
+    if corpus.kind_of(listed.uid, listed.data) != "data":
+        return flags
+    held = tuple(str(key) for key in corpus.entries(listed.data) or {})
+    return [dataclasses.replace(flag, choices=held)
+            if flag.dest == "value_type" else flag for flag in flags]
+    # @req- 54mksz
+
+
+def build_parser(root, fielded):
+    flags = _value_typed(root, _fields.flags(root)) if fielded else []
+    clears = _fields.clears(root) if fielded else []
+    p = argparse.ArgumentParser(
+        prog="reqctl",
+        description="The requirements corpus under requirements/ is read and "
+                    "written only through these commands. --json goes before "
+                    "the command: reqctl --json <command> ...",
+    )
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    # @req> REQ-94206537@I4xcLLW1nbOH 47la7c
+    p.add_argument("--version", action="version",
+                   version=importlib.metadata.version("reqctl"))
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = _command(sub, "new", "mint a requirement, parameter, term or data item")
+    _item_arguments(s, flags)
+    s.add_argument("--uid", help="mint a requirement or guard under this uid "
+                                 "rather than a fresh one")
+    s.set_defaults(func=cmd_new)
+
+    s = _command(sub, "lint",
+                 "report the faults new would refuse an item for, writing "
+                 "nothing")
+    _item_arguments(s, flags)
+    s.set_defaults(func=cmd_lint)
+
+    s = _command(sub, "revise",
+                 "change an item's fields, pin its links with --ack, or edit "
+                 "a data entry")
+    # @req> REQ-94401451@EZFY5LjHcj9g znwuir
+    s.add_argument("uid", nargs="+")
+    # @req> REQ-91205530@FiUaykViw6dQ ctnzp2
+    _field_arguments(s, flags + clears, _write.OPERATIONS)
+    s.add_argument("--ack", dest="ack", action="append",
+                   metavar="NAME | NAME.ENTRY",
+                   help="pin a referenced parameter or linked term at its "
+                        "current state; repeat for each one")
+    s.add_argument("--handle", metavar="KEY",
+                   help="terms: the entry key, snake_case; the word it wore "
+                        "moves into the entry where a word is not already "
+                        "stated")
+    s.add_argument("--kind", choices=list(_write.KINDS))
+    s.add_argument("--entry", metavar="KEY",
+                   help="the existing entry --set writes to")
+    s.add_argument("--new-entry", dest="new_entry", metavar="KEY",
+                   help="add a data entry, applying --set to it")
+    s.add_argument("--set", dest="set", action="append", metavar="FIELD=VALUE",
+                   help="a field on --entry's entry; repeat for each one")
+    s.add_argument("--append", dest="append", action="append",
+                   metavar="FIELD=VALUE",
+                   help="add one member to a set field; repeat for each member")
+    s.add_argument("--unset", dest="unset", action="append", metavar="FIELD",
+                   help="drop a field from --entry's entry; repeat for each one")
+    s.add_argument("--drop-entry", dest="drop_entry", metavar="KEY",
+                   help="remove a data entry; its fields go with it")
+    s.add_argument("--reword", dest="reword", action="append", metavar="OLD=NEW",
+                   help="a word this term's links show, and what it becomes; "
+                        "--term rewrites its own word without this")
+    s.set_defaults(func=cmd_revise)
+
+    s = _command(sub, "relate",
+                 "record a relation between requirements, from the statement "
+                 "making the claim toward the one it leans on")
+    s.add_argument("source", help="the requirement making the claim")
+    s.add_argument("relation", choices=list(_write.RELATIONS))
+    s.add_argument("target", help="the requirement it points at")
+    s.set_defaults(func=cmd_relate)
+
+    s = _command(sub, "repin-links",
+                 "pin every link and reference awaiting assessment in the items "
+                 "named, or with --all in every item, checking the corpus once")
+    s.add_argument("uids", nargs="*", metavar="UID")
+    s.add_argument("--all", action="store_true")
+    s.set_defaults(func=cmd_repin_links)
+
+    s = _command(sub, "unrelate", "remove a relation")
+    s.add_argument("source")
+    s.add_argument("target")
+    s.set_defaults(func=cmd_unrelate)
+
+    s = _command(sub, "rename",
+                 "give a term, a parameter or a data item another name, "
+                 "moving its file and every reference that reaches it")
+    s.add_argument("uid")
+    s.add_argument("name")
+    s.set_defaults(func=cmd_rename)
+
+    s = _command(sub, "refile",
+                 "file a parameter as the data item it is, moving its file "
+                 "and dropping the value_type a data item does not carry; "
+                 "with --into DATA KEY, as an entry of DATA under KEY instead")
+    s.add_argument("uid")
+    s.add_argument("--into", nargs=2, metavar=("DATA", "KEY"))
+    s.set_defaults(func=cmd_refile)
+
+    s = _command(sub, "delete",
+                 "remove a draft nothing points at; an item the corpus has "
+                 "stated is deprecated, never removed")
+    s.add_argument("uid")
+    s.set_defaults(func=cmd_delete)
+
+    s = _command(sub, "export",
+                 "print the corpus as markdown, or raw with --json")
+    s.add_argument("--all", action="store_true", help="include drafts and deprecated")
+    s.set_defaults(func=cmd_export)
+
+    s = _command(sub, "context",
+                 "everything around each item named: fields, links, suspicion, "
+                 "code. Inspection only -- what it cannot read it marks, and it "
+                 "fails only when nothing named resolves or the scan for code "
+                 "citations meets a file or folder it cannot read")
+    s.add_argument("uid", nargs="+", metavar="UID")
+    s.set_defaults(func=cmd_context)
+
+    s = _command(sub, "list",
+                 "one line per item -- what the corpus holds, without "
+                 "reading all of it")
+    s.add_argument("kind", nargs="?",
+                   choices=list(_write.KINDS),
+                   help="limit to one kind; omit for everything")
+    s.set_defaults(func=cmd_list)
+
+    s = _command(sub, "validate",
+                 "check every item and every cross-link; exit 1 on problems")
+    s.add_argument("--verbose", action="store_true")
+    s.set_defaults(func=cmd_validate)
+
+    s = _command(sub, "trace",
+                 "map @req tags in code to the corpus; exit 1 on problems")
+    s.add_argument("uid", nargs="?", help="limit the trace to one item")
+    # @req> REQ-27097724@WuK_Hn1OEs1s updzi2
+    s.add_argument("--base")
+    # @req> REQ-21635723@CvxpeHCRTgGz rji7bg
+    s.add_argument("--record", action="store_true")
+    s.set_defaults(func=cmd_trace)
+
+    s = _command(sub, "tag",
+                 "cite a requirement, a guard, a parameter, a data item or one "
+                 "entry of a data item at lines of a file, writing one comment "
+                 "over a single code statement and a pair of comments over "
+                 "more; repeat --from, --to and --req to cite several, each "
+                 "numbered as the file stands before the command; --name a "
+                 "function, class or method of a .py file in place of --from and "
+                 "--to; name none of them to cite a whole file")
+    s.add_argument("path")
+    # @req+ REQ-62782894@x4o_oB5H0-tY ou2zvt
+    s.add_argument("--from", dest="first", type=int, action="append")
+    s.add_argument("--to", dest="last", type=int, action="append")
+    s.add_argument("--req", action="append", required=True)
+    # @req- ou2zvt
+    # @req> REQ-74702510@gU2X5OnlUbY3 ntl5o7
+    s.add_argument("--name", dest="names", action="append")
+    s.add_argument("--exclusive", action="store_true")
+    s.set_defaults(func=cmd_tag)
+
+    s = _command(sub, "repin",
+                 "re-pin citations to the stamp their items carry now, "
+                 "once the code is read against the statement that stands")
+    s.add_argument("id", nargs="+")
+    s.set_defaults(func=cmd_repin)
+
+    s = _command(sub, "untag",
+                 "remove a citation; name a path and --req to remove that "
+                 "item's whole-file citation of the path")
+    s.add_argument("id", metavar="ID|PATH")
+    s.add_argument("--req", action="append")
+    s.set_defaults(func=cmd_untag)
+
+    s = _command(sub, "unlist",
+                 "remove from an item's citation list an identity that no "
+                 "citation of that item names")
+    s.add_argument("uid")
+    s.add_argument("id")
+    s.set_defaults(func=cmd_unlist)
+
+    s = _command(sub, "compare",
+                 "state which citations this branch added, deleted, moved or "
+                 "changed since it left the default branch, and the items "
+                 "they name")
+    s.add_argument("--base")
+    s.set_defaults(func=cmd_compare)
+
+    s = _command(sub, "portal",
+                 "serve the portal on the repository origin names, and open "
+                 "the browser at it")
+    s.set_defaults(func=cmd_portal)
+
+    s = _command(sub, "resolve",
+                 "settle an item whose unresolved merge falls within its "
+                 "pins and citation list, dropping the pins and citations the "
+                 "merge conflicted")
+    s.add_argument("uid")
+    s.set_defaults(func=cmd_resolve)
+
+    s = _command(sub, "baseline", "the manifest of what is approved")
+    g = s.add_mutually_exclusive_group(required=True)
+    g.add_argument("--check", action="store_true",
+                   help="compare the baseline against the corpus")
+    g.add_argument("--generate", action="store_true",
+                   help="write the next baseline from what is approved")
+    s.set_defaults(func=cmd_baseline)
+
+    return p
+
+
+def _drop_output():
+    try:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    except (OSError, ValueError):
+        pass
+
+
+# @req> REQ-61484030@LpHoz6FzkKeT s75lcl
+# @req> REQ-19913588@hBNJrpn4vtZe irna4n
+def _fault(as_json, error):
+    try:
+        if sys.stdout is not None:
+            if as_json:
+                print(json.dumps({"error": str(error)}, indent=2), flush=True)
+                return EXIT_INVALID
+            sys.stdout.flush()
+    except OSError:
+        _drop_output()
+    print(f"reqctl: {error}", file=sys.stderr)
+    return EXIT_INVALID
+
+
+# @req> REQ-19913588@hBNJrpn4vtZe dsaqmg
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # @req+ REQ-19913588@hBNJrpn4vtZe zh6xly
+    try:
+        parser = build_parser(_fields.root(), _fielded(argv))
+    except (ReqctlError, OSError, UnicodeError) as error:
+        return _fault("--json" in argv, error)
+    # @req- zh6xly
+    # @req+ REQ-30898926@Vu28eWaG_1mE wwtx5y
+    said = io.StringIO()
+    try:
+        with contextlib.redirect_stderr(said):
+            args = parser.parse_args(argv)
+    except SystemExit as usage:
+        # @req> REQ-61484030@LpHoz6FzkKeT 7acuon
+        if "--json" in argv and usage.code and sys.stdout is not None:
+            try:
+                print(json.dumps({"error": said.getvalue().strip()}, indent=2),
+                      flush=True)
+                raise
+            except OSError:
+                _drop_output()
+        with contextlib.suppress(AttributeError, OSError):
+            sys.stderr.write(said.getvalue())
+        raise
+    # @req- wwtx5y
+    # @req+ REQ-19913588@hBNJrpn4vtZe dw57fs
+    try:
+        # @req> REQ-51372579@dWaIOhXJzQnK 7fex4d
+        if sys.stdout is None:
+            reader, writer = os.pipe()
+            os.close(reader)
+            sys.stdout = os.fdopen(writer, "w")
+        # @req> REQ-24406170@ffuKefeAdU7p 3ofubr
+        with corpus.all_or_nothing():
+            done = args.func(args)
+            sys.stdout.flush()
+            return done
+    except BrokenPipeError:
+        _drop_output()
+        # @req> REQ-51372579@dWaIOhXJzQnK ihfdn7
+        return EXIT_INVALID
+    except (ReqctlError, OSError, UnicodeError) as error:
+        return _fault(args.json, error)
+    # @req- dw57fs