@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/registry.py

@@ -0,0 +1,382 @@
+import re
+from pathlib import Path
+
+from . import ids
+from .tree import RESERVED_MD, _repo_files
+from .frontmatter import (as_list, parse_frontmatter, split_frontmatter, title_of,
+                          unquote)
+
+# NOTE: this module imports `ids` as a MODULE and reads `ids.ID` / `ids.LEDGER`
+# at call time, never `from .ids import ID`. A name bound at import time would
+# capture the shipped default and survive `ids.configure()`, so a repo whose
+# prefix is not the default would have its entire ledger reported as dangling.
+
+
+class Domain:
+    """A `work/<name>/README.md` with `type: domain` — the doc you land on when
+    you open the domain's folder, and a surface that may HOST rules.
+
+    All domains host, not just architecture. A rule about *how we know it's good*
+    or *how we reach users* previously had nowhere to live and got mis-filed under
+    `architecture/<system>`; a domain that owns a kind of call must be able to own
+    that call's id. The shape is identical to a system's — `### <id>` +
+    `enforced_by:` — so `_parse_rules` serves both and no check knows a filename.
+
+    `code` is read only to REFUSE it: regions belong to systems, one region to
+    exactly one owner. A domain inventing a `tests`/`ci` region would overlap every
+    system and break the vocabulary the whole `code:` field rests on, so `align`
+    reports it rather than the parser quietly accepting it."""
+
+    def __init__(self, folder: Path):
+        self.folder = folder
+        self.name = folder.name
+        self.md = folder / "README.md"
+        text = self.md.read_text()
+        self.fm = parse_frontmatter(text)
+        self.title = title_of(self.md)
+        self.code = as_list(self.fm.get("code"))
+        self.rules = _parse_rules(split_frontmatter(text)[1])
+        self.titles = rule_titles(split_frontmatter(text)[1])
+class System:
+    """A `work/architecture/<name>.md`. `code` is the region vocabulary it owns;
+    `rules` maps each hosted ledger id to its `enforced_by`."""
+
+    def __init__(self, md: Path):
+        self.md = md
+        self.name = md.stem
+        text = md.read_text()
+        self.fm = parse_frontmatter(text)
+        self.title = title_of(self.md)
+        self.code = as_list(self.fm.get("code"))
+        self.paths = [unquote(p) for p in as_list(self.fm.get("paths"))]
+        self.depends_on = as_list(self.fm.get("depends_on"))
+        self.rules = _parse_rules(split_frontmatter(text)[1])
+        self.titles = rule_titles(split_frontmatter(text)[1])
+#: A value that is ENTIRELY italic — `_…_` or `*…*` — is a placeholder, not evidence.
+#: Every scaffold in the harness writes its blanks in italics, so this is the shape a
+#: rule wears before anybody has said what catches it. Found by dogfooding `id-new`:
+#: a freshly allocated rule shipped `enforced_by: _the check…_` and `where` reported
+#: it as ENFORCED, which is a false green in exactly the check that exists to catch
+#: wishes. `*(…)*` was already handled; `_…_` is the same convention.
+_ITALIC_ONLY = re.compile(r"^[_*].*[_*]$")
+
+
+def _parse_rules(body: str) -> dict:
+    """`{id: enforced_by}` from a hosting doc's `### <id>` entries.
+
+    The PROSE IS THE DEFINITION: the id is its `###` heading and its evidence is
+    the `enforced_by:` line directly under it. The hand-kept summary table this
+    used to parse is DELETED, not generated — a table three lines above the entry
+    it summarises is one more thing to keep in sync, which is the bug class this
+    system exists to remove.
+
+    The word is RULE, not "invariant". A domain README and a system doc host the
+    same shape, so one parse serves both.
+
+    An `enforced_by:` that is missing, an italic `*(…)*` note, or a value that
+    OPENS with a dash counts as NOT enforced — that is what `align` reports as "a
+    rule nothing can catch is a wish", so the parse must not paper over it.
+
+    The dash is a PREFIX test, not equality. The honest-debt convention is
+    `enforced_by: — not yet`, and matching only a bare `—` let every one of those
+    through as real evidence: the triage rule that exists to admit debt was
+    silently hiding it."""
+    found = {}
+    for m in re.finditer(rf"^###\s+{ids.pattern()}\b.*?$\n(.*?)(?=^###?\s|\Z)",
+                         body, re.MULTILINE | re.DOTALL):
+        id_, rest = ids.normalise(m.group(1)), m.group(2)
+        ev = re.match(r"\s*enforced_by:\s*(.*?)\s*$", rest, re.MULTILINE)
+        evidence = ev.group(1).strip() if ev else ""
+        if evidence.startswith(("—", "-", "*(")) or _ITALIC_ONLY.match(evidence):
+            evidence = ""
+        found[id_] = evidence
+    return found
+def rule_titles(body: str) -> dict:
+    """`{id: title}` from the same `### <id> — title` headings `_parse_rules` reads.
+
+    A second READER of one heading, never a second definition of what a rule is:
+    `_parse_rules` answers *what catches this*, and this answers *what is it called*.
+    Both come off the line the author wrote, so neither can describe a rule the other
+    does not see.
+
+    Titles are what a session start injects. Names alone are what make a rule
+    reachable — a session that has been told `J-33` exists and is about which machine
+    answers goes and reads it before routing something; one that has been told
+    nothing does not know there is anything to look up.
+    """
+    found = {}
+    for m in re.finditer(rf"^###\s+{ids.pattern()}\s*[—–-]*\s*(.*?)\s*$",
+                         body, re.MULTILINE):
+        found[ids.normalise(m.group(1))] = m.group(2).strip()
+    return found
+#: A rule whose only enforcement is a person deciding. LEGAL — `commercial` is made
+#: of them, and the routing test already says strategy is enforced by judgement —
+#: but never silent: `align` tallies these on their own line so "a person decides"
+#: cannot quietly become the way to make the no-enforced-by warning go away.
+_JUDGEMENT = re.compile(r"^judgement\b", re.IGNORECASE)
+
+
+def is_judgement(evidence: str) -> bool:
+    return bool(_JUDGEMENT.match(evidence.strip()))
+def _is_domain(md: Path) -> bool:
+    """A domain is declared by its README's `type: domain`, not by the filename.
+    `README.md` is the universal landing name, so it is the FRONTMATTER that
+    separates an org-domain from any other folder that grows one."""
+    return md.is_file() and parse_frontmatter(md.read_text()).get("type") == "domain"
+#: The reading order of the org-domain map, not alphabetical: what it does → how
+#: it's built → how it looks → how we know it's good → what keeps it safe → how we
+#: run it → how users get unblocked → how we reach and earn → what binds us.
+#: A repo overrides this through `domains.order` in its config; a domain not on the
+#: list still scans, it just sorts last.
+DOMAIN_ORDER = ("product", "architecture", "design", "quality", "security",
+                "operations", "support", "commercial", "legal")
+
+
+def scan_domains(root: Path) -> list:
+    """Every `work/<dir>/README.md` that declares `type: domain`, in reading
+    order."""
+    found = [Domain(p) for p in sorted(root.iterdir())
+             if p.is_dir() and _is_domain(p / "README.md")]
+    return sorted(found, key=lambda d: (DOMAIN_ORDER.index(d.name)
+                                        if d.name in DOMAIN_ORDER else len(DOMAIN_ORDER),
+                                        d.name))
+def scan_systems(root: Path) -> list:
+    arch = root / "architecture"
+    if not arch.is_dir():
+        return []
+    return [System(p) for p in sorted(arch.glob("*.md"))
+            if p.name not in RESERVED_MD]
+def code_vocabulary(root: Path) -> tuple:
+    """The `code:` regions a task may draw from — the UNION of what the systems
+    declare. Replaces the hand-curated tuple this used to be: a region exists
+    because a system owns it, so the two can no longer disagree."""
+    regions = set()
+    for s in scan_systems(root):
+        regions.update(s.code)
+    return tuple(sorted(regions))
+def systems_for_code(root: Path, code: list) -> list:
+    """The systems a task's `code:` regions land in — `task.code ∩ system.code`.
+    This is how a task's constraining rules are derived rather than remembered."""
+    wanted = set(code)
+    return [s for s in scan_systems(root) if wanted & set(s.code)]
+def _glob_re(pattern: str):
+    """A `paths:` glob as a regex.
+
+    Hand-rolled rather than `fnmatch`, whose `*` happily crosses a `/` — under it
+    `packages/*/src` claims `packages/a/b/src` and a system swallows its neighbours.
+    Here `*` stops at a separator and only `**` spans them, which is what the globs
+    in these files are written to mean.
+
+    The mirror of this lives in `apps/cli/src/hooks/applies.ts`, which replays the same
+    globs without paying for a Python start. Two hand-written matchers is a real cost,
+    and it is paid deliberately: the tests on both sides assert the same cases, and the
+    alternative on the TypeScript side was a 53ms module load before every tool call.
+    """
+    out, i = [], 0
+    while i < len(pattern):
+        ch = pattern[i]
+        if ch == "*":
+            if pattern[i + 1:i + 2] == "*":
+                out.append(".*")
+                i += 2
+                continue
+            out.append("[^/]*")
+        elif ch == "?":
+            out.append("[^/]")
+        else:
+            out.append(re.escape(ch))
+        i += 1
+    return re.compile("".join(out) + r"\Z")
+def _claims(declared: str, path: str) -> bool:
+    """Whether a system's declaration covers this file.
+
+    **Two forms are in use across these repos and both are meant.** A PATTERN —
+    anything carrying `*` or `?` — is a glob and is matched as one. A bare PATH is
+    what a document writes when it names which part of a repo it is about, and
+    `packages/mcp` there means that directory's contents, not a file literally called
+    `mcp`, which is the only thing a glob matcher would hand back.
+
+    Found by running this against a sibling: jarvis writes `packages/data/src/**` and
+    gotcha writes `packages/mcp`, so a glob-only reader is correct in one repo and
+    silently says nothing in the other — the worst shape available, because nothing
+    fails and the rules simply never arrive.
+    """
+    declared = declared.rstrip("/")
+    if "*" in declared or "?" in declared:
+        return bool(_glob_re(declared).match(path))
+    return path == declared or path.startswith(f"{declared}/")
+def system_paths(root: Path, systems=None) -> list:
+    """Every system that declares where its code lives, as `(name, globs)`.
+
+    The pairs a caller needs to answer "which system is this file in?" without
+    re-reading the tree for each question — and the whole of what a client outside
+    Python has to be handed to ask the same thing.
+
+    `systems` takes an already-scanned list, for a caller asking this and
+    `system_for_path` in one breath: the scan reads and parses every architecture
+    doc, and doing it twice for two questions about one tree is pure waste.
+    """
+    scanned = scan_systems(root) if systems is None else systems
+    return [(s.name, list(s.paths)) for s in scanned if s.paths]
+def system_for_path(root: Path, path: str, systems=None):
+    """The system whose declared globs claim this repo-relative path, or None.
+
+    A file under no system, and a repo whose systems declare nothing, are the same
+    answer: nothing to say. Both are silence rather than a guess, because a wrong
+    system names the wrong rules and that is worse than naming none.
+
+    Two systems claiming one path is not resolved here — the first in filename order
+    wins, deterministically. It means the declarations overlap, which the graph build
+    is the right place to complain about.
+
+    `systems` takes an already-scanned list, so a caller with two questions about one
+    tree pays for reading it once.
+    """
+    clean = str(path).replace("\\", "/")
+    if clean.startswith("./"):
+        clean = clean[2:]
+    for s in (scan_systems(root) if systems is None else systems):
+        if any(_claims(declared, clean) for declared in s.paths):
+            return s
+    return None
+def locate_system(root: Path, name: str):
+    """The system's spec FILE, or None — the mirror of `locate_feature`. A system
+    has no directory: `architecture/<system>.md` is its whole address."""
+    md = root / "architecture" / f"{name}.md"
+    return md if md.is_file() and md.name not in RESERVED_MD else None
+def locate_domain(root: Path, name: str):
+    folder = root / name
+    return folder if _is_domain(folder / "README.md") else None
+def _heading_list(md: Path) -> list:
+    """Every `### <id> — …` in one file, as `[(id, title), …]` IN ORDER and with
+    repeats kept. Deduping here would hide a second definition site, which is the
+    exact defect `align` exists to catch."""
+    if not md.is_file():
+        return []
+    return [(ids.normalise(m.group(1)), m.group(2).strip())
+            for m in ids.titled_heading(3).finditer(md.read_text())]
+def _headings(md: Path) -> dict:
+    """`{id: title}` for one file — first occurrence wins."""
+    found = {}
+    for id_, title in _heading_list(md):
+        found.setdefault(id_, title)
+    return found
+def definition_surfaces(root: Path) -> list:
+    """Every `(home, path)` that may DEFINE an id — the one list, computed once.
+
+    Each `architecture/<system>.md` ∪ each org-domain's `README.md`. Nothing
+    downstream names a file: `definition_sites`, `resolve_id`, `where` and
+    `align`'s heading-form check all iterate this, so adding a hosting surface is a
+    change here and nowhere else.
+
+    That generality is the whole point. Only two surfaces could host before, which
+    is why a quality or commercial rule had to be mis-filed under
+    `architecture/<system>` — the doc that owns the *kind* of call could not own
+    its *id*. `align` special-casing a ledger by filename was the same bug one
+    layer up.
+
+    `DECISIONS.md` is read if present, but is NOT the model: the ledger dissolves,
+    and a rule lives in the domain that owns it. It stays on the list only so a repo
+    mid-migration reads correctly rather than reporting its whole ledger dangling.
+    """
+    surfaces = []
+    legacy = root / "DECISIONS.md"
+    if legacy.is_file():
+        surfaces.append(("DECISIONS.md", legacy))
+    surfaces += [(f"architecture/{s.name}", s.md) for s in scan_systems(root)]
+    # `architecture/README.md` is the architecture DOMAIN's landing doc, and
+    # `scan_systems` skips RESERVED_MD — so it arrives here exactly once, through
+    # `scan_domains`, and never double-counts as both a system and a domain.
+    surfaces += [(f"{d.name}/README", d.md) for d in scan_domains(root)]
+    return surfaces
+def definition_sites(root: Path) -> dict:
+    """`{id: [(home, title), …]}` across every definition surface.
+
+    Re-homing moves a rule without moving its id, so "is this id defined?" stops
+    being a question about one file. A list, not a single home, because a second
+    entry is a finding `align` must report rather than a state the resolver
+    silently picks a winner from."""
+    sites: dict = {}
+    for home, md in definition_surfaces(root):
+        for id_, title in _heading_list(md):
+            sites.setdefault(id_, []).append((home, title))
+    return sites
+def hosts(root: Path) -> list:
+    """Every doc that HOSTS rules — systems and domains alike — as
+    `(home, name, rules, code)`. The union `align` checks one-home-per-id over, so
+    an id cannot sit in `quality/README.md` and `architecture/harness.md` at once
+    and have each half of the check believe the other owns it."""
+    out = [(f"architecture/{s.name}", s.name, s.rules, s.code)
+           for s in scan_systems(root)]
+    out += [(f"{d.name}/README", d.name, d.rules, d.code)
+            for d in scan_domains(root)]
+    return out
+def hosted_rules(root: Path) -> list:
+    """`[(home, id, title)]` for every rule this repo hosts, systems then domains.
+
+    The same walk `hosts` makes, carrying the titles instead of the evidence —
+    because what a session start needs is the NAME of every decision already taken
+    here, and what `align` needs is what catches each one.
+    """
+    out = [(f"architecture/{s.name}", i, t) for s in scan_systems(root)
+           for i, t in s.titles.items()]
+    out += [(d.name, i, t) for d in scan_domains(root) for i, t in d.titles.items()]
+    return out
+def rules_by_domain(root: Path) -> dict:
+    """`{domain: count}` — every rule hosted ANYWHERE under a domain's folder.
+
+    Not the same as `Domain.rules`, and the difference is the whole point.
+    `Domain.rules` reads that domain's own `README.md`, which is correct for
+    resolution: a rule in `architecture/harness.md` belongs to the *harness system*,
+    not to the architecture README. But it is wrong for a MAP — `architecture` hosted
+    four rules through its systems and printed as hosting none, which reads as an
+    empty domain rather than a busy one.
+
+    So the map counts by folder and resolution counts by host, and each is right for
+    its question.
+    """
+    counts = {d.name: len(d.rules) for d in scan_domains(root)}
+    if "architecture" in counts:
+        counts["architecture"] += sum(len(s.rules) for s in scan_systems(root))
+    return counts
+def resolve_id(root: Path, id_: str):
+    """`(home, title)` for an id, or `None`. The one lookup `where` and every
+    dangling-citation check share, so they can never disagree about what
+    resolves."""
+    sites = definition_sites(root).get(ids.normalise(id_))
+    if sites:
+        return sites[0]
+    for home, _, rules, _ in hosts(root):
+        if ids.normalise(id_) in rules:
+            return (home, "")
+    return None
+def domains_for_owner(root: Path, owner: str) -> list:
+    """The domains whose rules constrain a task, resolved from `task.owner`.
+
+    Domains declare no `code:`, so they cannot be derived the way systems are
+    (`task.code ∩ system.code`) — the owner link is what keys them. An owner is
+    either a bare domain name or a bare FEATURE name, and a feature lives in
+    `product/`, so a feature owner resolves to the **product** domain. That is
+    derived from where the spec sits, not remembered, which is why there is no
+    feature→domain table to keep in sync."""
+    if not owner:
+        return []
+    by_name = {d.name: d for d in scan_domains(root)}
+    if owner in by_name:
+        return [by_name[owner]]
+    if (root / "product" / f"{owner}.md").is_file() and "product" in by_name:
+        return [by_name["product"]]
+    return []
+def _citation_counts(root: Path) -> dict:
+    """How many files cite each ledger id, repo-wide excluding generated caches.
+    This is what makes "an id is permanent" a measurable claim rather than a
+    slogan — `where` prints it so nobody renumbers casually."""
+    counts: dict = {}
+    for p in _repo_files(root.parent):
+        try:
+            text = p.read_text(errors="ignore")
+        except Exception:
+            continue
+        for id_ in {ids.normalise(m.group(0)) for m in ids.ID.finditer(text)}:
+            counts[id_] = counts.get(id_, 0) + 1
+    return counts

package/harness/harness/report.py

@@ -0,0 +1,227 @@
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from .tree import find_work_root, rel
+from .frontmatter import _eol, read_item, split_frontmatter, write_item
+from .model import Task, _ordered, scan
+from .lint import lint_warnings
+from .generate import _regen_readme, _sync, settle_epic_tier
+from .align import (_align_acceptance, _align_agents, _align_citations,
+                    _align_definitions, _align_domains, _align_hosts,
+                    _align_ledger_index, _align_retired, _align_single_feature,
+                    _align_versions)
+from .registry import rules_by_domain, scan_domains
+
+
+def _task_line(t: Task) -> str:
+    extra = []
+    if t.depends_on:
+        extra.append("depends on: " + ", ".join(t.depends_on))
+    if t.artifacts:
+        extra.append(f"{len(t.artifacts)} plan/analysis file(s)")
+    if t.sessions:
+        extra.append(f"{len(t.sessions)} session(s)")
+    if t.completed:
+        extra.append(f"completed {t.completed}")
+    tail = ("  [" + " · ".join(extra) + "]") if extra else ""
+    status = t.display_status()
+    return f"{status:>11}  {t.priority}  {t.name} — {t.title}{tail}"
+def _say_staleness(root) -> None:
+    """Print how far behind the origin this checkout is, or nothing when it is level.
+
+    The board and the map answer from the same checkout and must never disagree about
+    how current they are; each derives it the same way — ask the origin, report a
+    count only when the origin answered — rather than one asking the other.
+    """
+    from . import git
+
+    note = git.staleness(root.parent)
+    if note:
+        print(f"  STALE  {note}\n")
+
+
+def cmd_list(args) -> int:
+    # Another branch's board is read from that ref's tree and printed on its own,
+    # never merged into this one's. Two branches are allowed to disagree — that is
+    # not the bug, and averaging them would hide the thing you asked to see.
+    if args.get("branch"):
+        from harness.branches import cmd_at
+        return cmd_at({"ref": args["branch"], **args})
+    root = find_work_root()
+    s = scan(root)
+
+    # A read does not pull, so the board on screen can be an older world than the
+    # origin's — and one that says nothing about it reads exactly like a current one.
+    # Said FIRST, above the board it qualifies, because a caveat under sixty lines of
+    # tasks is a caveat nobody reaches.
+    _say_staleness(root)
+
+    # The domain map, in READING ORDER — what it does -> how it is built -> … ->
+    # what binds us. Printed before the board because it is the map a cold session
+    # needs to know where a call goes; `scan_domains` already sorts by
+    # `domains.order`, so this line cannot disagree with the tree.
+    domains = scan_domains(root)
+    if domains:
+        counts = rules_by_domain(root)
+        cells = [f"{d.name}({counts[d.name]})" if counts.get(d.name) else d.name
+                 for d in domains]
+        print("DOMAINS  " + " · ".join(cells) + "        (n) = rules hosted")
+
+    if not s["versions"] and not s["backlog"]:
+        print("\nbacklog is empty")
+        return 0
+
+    for v in sorted(s["versions"], key=lambda x: (x.order, x.name)):
+        flag = {
+            "released": f" · released {v.released}",
+            "current": " · current",
+            "planned": " · planned",
+        }[v.status()]
+        target = f" · target {v.target}" if v.target and not v.released else ""
+        print(f"\nVERSION  {v.name} — {v.title}{flag}{target}")
+        if v.outcome:
+            print(f"         {v.outcome}")
+        for t in _ordered(v.tasks):
+            print(f"    {_task_line(t)}")
+        # Moving epics first and in full; finished ones collapse to a line at the
+        # bottom. The tier they sit in is the same fact, so the board and the tree
+        # agree without either being told twice.
+        moving = [e for e in v.epics if not e.done_tier]
+        done = [e for e in v.epics if e.done_tier]
+        for e in moving:
+            print(f"\n  EPIC   {e.name} — {e.title}"
+                  + ("" if e.planned else "  (archived at release)"))
+            if e.continues:
+                print(f"         ↳ continues {e.continues} — its plan still holds")
+            for t in _ordered(e.tasks):
+                print(f"    {_task_line(t)}")
+        for e in done:
+            n = len(e.all_tasks())
+            print(f"\n  DONE   {e.name} — {e.title}  ({n}/{n})")
+
+    if s["backlog"]:
+        print("\nBACKLOG  (unscheduled — pull an epic into a version to start)")
+        for e in s["backlog_epics"]:
+            print(f"\n  EPIC   {e.name} — {e.title}")
+            if e.continues:
+                print(f"         ↳ continues {e.continues} — its plan still holds")
+            for t in sorted(e.backlog_tasks,
+                            key=lambda x: (x.priority_rank(), x.name)):
+                print(f"    {_task_line(t)}")
+        loose = sorted((t for t in s["backlog"] if not t.epic),
+                       key=lambda x: (x.priority_rank(), x.name))
+        if loose:
+            print()
+            for t in loose:
+                print(f"    {_task_line(t)}")
+    print()
+    warns = lint_warnings(root)
+    if warns:
+        print("LINT")
+        for w in warns:
+            print(f"  WARN  {w}", file=sys.stderr)
+        print()
+    return 0
+def cmd_readme(args) -> int:
+    """Regenerate what is DERIVED. An epic's tier is derived too — from whether its
+    tasks are all complete — so it settles here alongside the table, which is also
+    what migrates a tree that predates the tier."""
+    root = find_work_root()
+    for name, where in settle_epic_tier(root):
+        print(f"epic '{name}' -> {where}")
+    print(_regen_readme(root))
+    return 0
+def misalignments(root: Path) -> list:
+    """Every misalignment the harness can find, as `(severity, class, message)`.
+
+    Separate from the command that prints them because `wrap` asks the same question
+    at the moment somebody is actually going to act on the answer. Two sweeps would be
+    two opinions about whether the tree hangs together.
+    """
+    s = scan(root)
+    return (_align_definitions(root) + _align_ledger_index(root)
+            + _align_citations(root) + _align_hosts(root)
+            + _align_domains(root)
+            + _align_single_feature(root) + _align_versions(root, s)
+            + _align_agents(root) + _align_retired(root) + _align_acceptance(root))
+
+
+def cmd_align(args) -> int:
+    """Report every misalignment class. REPORT-ONLY, exit 0 — by founder call.
+
+    With coverage still partial, a blocking gate would just be permanently red,
+    and a lint that is always red is a lint nobody reads. The flip to blocking is
+    the goal and becomes its own task once coverage is real."""
+    root = find_work_root()
+    findings = misalignments(root)
+    only = args.get("class")
+    if only:
+        findings = [f for f in findings if f[1] == only]
+
+    errors = [f for f in findings if f[0] == "error"]
+    warns = [f for f in findings if f[0] == "warn"]
+    # `info` is not a lesser warning — it is a COUNT of something legitimate that
+    # must stay visible (today: rules enforced by a person deciding). Folded into
+    # the warning total it would look like debt; dropped, it would let "a person
+    # decides" become the silent way to clear the no-enforced-by warning.
+    infos = [f for f in findings if f[0] == "info"]
+    for sev, cls, msg in errors + warns + infos:
+        mark = {"error": "✗", "warn": "⚠"}.get(sev, "·")
+        print(f"  {mark} {cls:20} {msg}")
+    if not findings:
+        print("  no misalignments found")
+    tail = f" · {len(infos)} note(s)" if infos else ""
+    print(f"\n  {len(warns)} warning(s) · {len(errors)} error(s){tail} · exit 0   "
+          f"(report-only — the flip to blocking is its own task)")
+    return 0
+def cmd_migrate_owner(args) -> int:
+    """Mechanical, one-way: `product:` becomes `owner:`, and the retired `infra`
+    sentinel becomes the `operations` domain. Skips files with uncommitted
+    changes unless --force: the tree is shared, and silently rewriting another
+    session's open edit is how a rename eats work that was never committed."""
+    root = find_work_root()
+    repo = root.parent
+    dirty = set()
+    try:
+        out = subprocess.run(["git", "status", "--porcelain"], cwd=repo,
+                             capture_output=True, text=True, check=True).stdout
+        for line in out.splitlines():
+            if len(line) > 3:
+                dirty.add((repo / line[3:].strip().strip('"')).resolve())
+    except Exception:
+        pass  # not a git repo, or git unavailable — migrate everything
+
+    def _is_dirty(md: Path) -> bool:
+        """Git reports an untracked DIRECTORY as the directory, not its files, so
+        a plain membership test misses `work/.../new-task/task.md` inside a folder
+        another session just created. Match the path or any parent."""
+        p = md.resolve()
+        return any(d == p or d in p.parents for d in dirty)
+
+    changed, skipped = [], []
+    for md in sorted(root.rglob("task.md")):
+        text = read_item(md)
+        fm, body = split_frontmatter(text)
+        if fm is None or not re.search(r"^product:", fm, re.MULTILINE):
+            continue
+        if _is_dirty(md) and not args.get("force"):
+            skipped.append(rel(md, root))
+            continue
+        # Only the KEY is rewritten — the value and its spacing are untouched, so
+        # 105 files change one word each instead of churning frontmatter layout.
+        new_fm = re.sub(r"^product:", "owner:", fm, flags=re.MULTILINE)
+        eol = _eol(text)
+        write_item(md, f"---{eol}{new_fm}{eol}---{eol}{body}")
+        changed.append(rel(md, root))
+
+    print(f"renamed product: -> owner: in {len(changed)} task.md")
+    if skipped:
+        print(f"SKIPPED {len(skipped)} with uncommitted changes (another session "
+              f"may be editing them) — rerun after they land, or pass --force:")
+        for f in skipped:
+            print(f"  {f}")
+    if changed:
+        _sync(root)
+    return 0