@antoneeo/mkt-agentic-sdlc-skill 0.26.0 → 0.27.0

package/skills/mkt-agentic-sdlc/scripts/knowledge.py

@@ -5,6 +5,7 @@ Extracted from the KB overlay; the kb_* API and stored formats remain compatible
 Every distribution ships this module alongside its entry point and sdlc_core.py.
 """
 import argparse
+import codecs
 import contextlib
 import io
 import os
@@ -13,6 +14,7 @@ import ntpath
 import posixpath
 import re
 import sys
+import time
 from pathlib import Path
 import sdlc_core
 from sdlc_core import *  # compatibility with the existing KB implementation
@@ -24,7 +26,7 @@ from sdlc_core import _map_refs
 
 CLAIM_COLUMNS = ("id", "claim", "valid", "qty", "about", "source", "prov", "state")
 CLAIM_HEADING = "## Claims"
-PROVENANCES = ("GIVEN", "ELICITED", "DERIVED", "RULING", "IMPORTED")
+PROVENANCES = ("GIVEN", "ELICITED", "DERIVED", "RULING", "IMPORTED", "DECLARED")
 SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
 OWNS_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$")
 DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
@@ -420,6 +422,40 @@ def kb_check_claims(root):
             meta, meta_where = (None, "")
             if "#" in first:
                 meta, meta_where = _declaring_frontmatter(first.rsplit("#", 1)[0])
+            # F-084: a declaration (a document this project SENT) can never pass
+            # for evidence, nor evidence for a declaration -- checked on EVERY
+            # source position, because corroboration appends sources to a row.
+            declared_srcs = []
+            for src in sources:
+                if "#" not in src:
+                    continue
+                path_s = src.rsplit("#", 1)[0]
+                if _resolved(path_s)[1]:
+                    smeta, swhere = _declaring_frontmatter(path_s)
+                    if ((smeta or {}).get("provenance") or "").strip().upper() == "DECLARED":
+                        declared_srcs.append((path_s, smeta, swhere))
+            if prov == "DECLARED":
+                decl_paths = set(d[0] for d in declared_srcs)
+                for src in sources:
+                    path_s = src.rsplit("#", 1)[0] if "#" in src else src
+                    if not _resolved(path_s)[1]:
+                        continue  # unresolvable source already reported
+                    if not path_s.startswith("corpus/given/") or path_s not in decl_paths:
+                        errors.append("%s: DECLARED row cites %s, which is not a "
+                                      "corpus/given/ artifact whose sidecar says "
+                                      "'provenance: DECLARED' -- a declaration rests "
+                                      "only on the document that was sent" % (where, path_s))
+                for path_s, smeta, swhere in declared_srcs:
+                    if not (smeta.get("recipient") or "").strip():
+                        errors.append("%s: DECLARED source (%s) carries no "
+                                      "'recipient:' -- a declaration names to whom it "
+                                      "was made" % (where, swhere))
+            elif declared_srcs:
+                errors.append("%s: prov %s, but %s declares 'provenance: DECLARED' -- "
+                              "a document this project sent is a declaration, not "
+                              "evidence: file the row as DECLARED on that artifact "
+                              "alone (a declaration never corroborates another row)"
+                              % (where, prov, declared_srcs[0][2]))
             if prov not in PROVENANCES:
                 errors.append("%s: prov %r not in %s" % (where, prov, "/".join(PROVENANCES)))
             elif prov in ("DERIVED", "RULING", "ELICITED", "IMPORTED"):
@@ -429,6 +465,16 @@ def kb_check_claims(root):
                     errors.append("%s: DERIVED claim's source (%s) carries no "
                                   "'derived_from:' — model knowledge disguised as "
                                   "a source" % (where, meta_where))
+                elif prov == "RULING" and meta.get("imported_from"):
+                    # F-083: relabelling an imported row RULING would make another
+                    # owner's note carry a decision here. Ratifying is deciding:
+                    # a note of your own, with your own basis.
+                    errors.append("%s: RULING source (%s) names a foreign origin "
+                                  "(imported_from: %s) — another project's note "
+                                  "cannot carry your ruling. Write your own note "
+                                  "with your own 'basis:' and put the RULING on it "
+                                  "(portability.md §4)"
+                                  % (where, meta_where, meta.get("imported_from")))
                 elif prov == "RULING" and not meta.get("basis"):
                     errors.append("%s: RULING source (%s) carries no 'basis:' — a "
                                   "preference is not a fact; no basis, no ruling"
@@ -448,7 +494,7 @@ def kb_check_claims(root):
                 # prose, and prose is not a check -- which is how three rows
                 # whose evidence was a reading of an image passed as GIVEN.
                 declared = ((meta or {}).get("provenance") or "").strip()
-                if declared and declared.upper() != "GIVEN":
+                if declared and declared.upper() not in ("GIVEN", "DECLARED"):
                     warnings.append(
                         "%s: prov GIVEN, but %s declares 'provenance: %s' — the "
                         "row reads as first-hand evidence and its artifact does "
@@ -571,13 +617,18 @@ def kb_check_claims(root):
             state = row["state"]
             if state == "OK":
                 continue
-            m = re.match(r"^(CONTESTED|SUPERSEDED) ([0-9a-f, ]+)$", state)
-            if not m:
-                errors.append("%s: state must be OK, 'CONTESTED <id>[,..]' or "
-                              "'SUPERSEDED <id>[,..]': %r" % (where, state))
+            kind, targets = _kb_states(state)
+            if not kind:
+                errors.append("%s: state must be OK, 'CONTESTED <id>[,..]', "
+                              "'SUPERSEDED <id>[,..]' or 'DIVERGES <id>[,..]': %r"
+                              % (where, state))
+                continue
+            row_decl = _kb_is_declared(row)
+            if kind == "DIVERGES" and not row_decl:
+                errors.append("%s: DIVERGES on a %s row -- only a DECLARED row "
+                              "diverges; two sources that disagree are CONTESTED"
+                              % (where, row["prov"].strip() or "?"))
                 continue
-            kind = m.group(1)
-            targets = [t.strip() for t in m.group(2).split(",") if t.strip()]
             for t in targets:
                 other = all_rows.get(t)
                 if other is None:
@@ -586,18 +637,38 @@ def kb_check_claims(root):
                                   "the check, it does not clean up" % (where, kind, t))
                     continue
                 orow, _ = other
+                if kind == "DIVERGES":
+                    if _kb_is_declared(orow):
+                        errors.append("%s: DIVERGES points at %s, a DECLARED row -- a "
+                                      "declaration diverges from the ledger, never from "
+                                      "another declaration (two sends that disagree "
+                                      "are CONTESTED)" % (where, t))
+                    elif orow["state"].startswith("SUPERSEDED"):
+                        errors.append("%s: DIVERGES points at SUPERSEDED row %s -- "
+                                      "re-judge the declaration against its successor"
+                                      " (OK if it now agrees)" % (where, t))
+                    continue
+                if kind in ("SUPERSEDED", "CONTESTED") and row_decl != _kb_is_declared(orow):
+                    errors.append("%s: %s %s across a declaration -- a declaration is "
+                                  "superseded only by a later declaration and never "
+                                  "settles or contests a fact; a declaration that "
+                                  "contradicts the ledger is DIVERGES"
+                                  % (where, kind, t))
+                    continue
                 if kind == "SUPERSEDED" and orow["prov"] == "IMPORTED":
                     # F-030, owner ruling 2026-08-03: knowledge crosses a project
                     # boundary, authority does not. An IMPORTED row carries another
                     # owner's decision; letting it supersede a local row would make
                     # that decision binding here without anyone here granting it.
-                    # Re-ratify first: write your own ruling note with your own
-                    # basis and flip the row to RULING.
+                    # Ratify first (F-083): a note of your own with your own basis,
+                    # a RULING row on it, and every row contested with the imported
+                    # one SUPERSEDED by that row.
                     errors.append("%s: SUPERSEDED by %s, which is IMPORTED — a "
                                   "foreign decision cannot settle a local row. "
-                                  "Re-ratify it (own note, own 'basis:', prov "
-                                  "RULING) or resolve this some other way"
-                                  % (where, t))
+                                  "Ratify it: your own note with your own "
+                                  "'basis:', a RULING row on it, and every row "
+                                  "CONTESTED with %s SUPERSEDED by that row"
+                                  % (where, t, t))
                 if kind == "CONTESTED":
                     if orow["state"].startswith("SUPERSEDED"):
                         errors.append("%s: CONTESTED points at SUPERSEDED row %s — "
@@ -703,6 +774,29 @@ def kb_drop_marks(text):
     return "\n".join(lines), dropped
 
 
+def _kb_is_declared(row):
+    return (row.get("prov") or "").strip().upper() == "DECLARED"
+
+
+def kb_has_declarations(selected):
+    """Whether any selected topic holds a DECLARED row -- a yes/no for export's
+    line, never a count (the same rule as F-080's dropped-marker line)."""
+    return any(_kb_is_declared(r) for _p, _t, rows in selected.values() for r in rows)
+
+
+def kb_drop_declarations(text):
+    """The topic text without its DECLARED rows (F-084: a declaration is this
+    project's commitment to its recipient and stays here). Every other line is
+    kept byte for byte. Closed by construction: check refuses any pointer from
+    a non-DECLARED row at a DECLARED one, so nothing left behind points at a
+    dropped row."""
+    rows, _ = kb_parse_claims(text)
+    gone = set(r["_line"] for r in rows if _kb_is_declared(r))
+    if not gone:
+        return text
+    return "\n".join(ln for i, ln in enumerate(text.split("\n"), 1) if i not in gone)
+
+
 def kb_check_locator(target, loc, where, errors, cache=None):
     """A locator must address an existing span of the stored bytes.
 
@@ -1773,21 +1867,29 @@ def kb_export_closure(docs, slugs):
     selected = dict((s, all_topics[s]) for s in slugs)
     # id -> slug, over the WHOLE graph, so a conflict partner is findable
     owner_of = {}
+    declared_ids = set()
     for slug, (_p, _t, rows) in all_topics.items():
         for r in rows:
             if r["id"]:
                 owner_of[r["id"]] = slug
+                if _kb_is_declared(r):
+                    declared_ids.add(r["id"])
     added = []
     pending = list(selected)
     while pending:
         slug = pending.pop()
         for r in selected[slug][2]:
-            m = re.match(r"^(CONTESTED|SUPERSEDED) ([0-9a-f, ]+)$", r["state"].strip())
-            if not m:
-                continue
-            for ref in [x.strip() for x in m.group(2).split(",") if x.strip()]:
+            if _kb_is_declared(r):
+                continue  # F-084: a declaration stays in this project
+            _kind, refs = _kb_states(r["state"])
+            for ref in refs:
                 other = owner_of.get(ref)
-                if other is None:
+                if ref in declared_ids:
+                    errors.append("claim %s in topic '%s' points at %s, a DECLARED row: "
+                                  "declarations are not exported and a fact never "
+                                  "points at one -- run check" % (r["id"] or "(no id)",
+                                                                   slug, ref))
+                elif other is None:
                     errors.append("claim %s in topic '%s' points at id %s, which "
                                   "no topic owns: export would carry a broken set"
                                   % (r["id"] or "(no id)", slug, ref))
@@ -1799,6 +1901,8 @@ def kb_export_closure(docs, slugs):
     seen = set()
     for slug, (_p, _t, rows) in sorted(selected.items()):
         for r in rows:
+            if _kb_is_declared(r):
+                continue  # its artifact stays with the declaration
             for rel in kb_claim_sources(r):
                 for cand in (rel, rel + ".meta.md",
                              rel[:-len(Path(rel).suffix)] + ".txt" if Path(rel).suffix else rel):
@@ -1824,6 +1928,7 @@ def kb_bundle_write(docs, out, selected, artifacts, project):
     for slug, (p, text, _rows) in sorted(selected.items()):
         text, d = kb_drop_marks(text)
         dropped = dropped or d
+        text = kb_drop_declarations(text)
         (out / "topics" / p.name).write_text(text, encoding="utf-8")
     for rel in artifacts:
         dst = out / rel
@@ -1841,10 +1946,338 @@ def kb_bundle_write(docs, out, selected, artifacts, project):
     return dropped
 
 
-def kb_import_plan(bundle, docs):
+def _kb_replace_cells(line, updates):
+    """One claim-table row with the cells at the given column indexes replaced;
+    everything else -- indentation, outer pipes, a CRLF tail -- verbatim."""
+    end = "\r" if line.endswith("\r") else ""
+    body = line[:-1] if end else line
+    lead = body[:len(body) - len(body.lstrip())]
+    s = body.strip()
+    opens, closes = s.startswith("|"), len(s) > 1 and s.endswith("|")
+    cells = s[1 if opens else 0:len(s) - 1 if closes else len(s)].split("|")
+    for i, v in updates.items():
+        cells[i] = " %s " % v
+    return "%s%s%s%s%s" % (lead, "|" if opens else "", "|".join(cells),
+                           "|" if closes else "", end)
+
+
+def _kb_states(state):
+    """'CONTESTED a, b' / 'SUPERSEDED a' / 'DIVERGES a' -> (kind, [ids]);
+    OK/other -> (None, []). The one parser of the full state grammar."""
+    m = re.match(r"^(CONTESTED|SUPERSEDED|DIVERGES) ([0-9a-f, ]+)$", (state or "").strip())
+    if not m:
+        return None, []
+    return m.group(1), [t.strip() for t in m.group(2).split(",") if t.strip()]
+
+
+def _kb_bom_text(data):
+    """(bom, text): a UTF-8 BOM (Windows authoring) is kept apart and given back
+    on write, as sdlc_core.read_text reads past it."""
+    bom = codecs.BOM_UTF8 if data.startswith(codecs.BOM_UTF8) else b""
+    return bom, data[len(bom):].decode("utf-8")
+
+
+def _kb_foreign_note(data, project, rel):
+    """F-083: the bytes of a ruling note as it lands in another project, and the
+    number of lines inserted. Lines go right after the opening '---' with the
+    note's own line ending; an existing origin line is rewritten in place, so it
+    moves nothing. None when the note opens no frontmatter."""
+    bom, text = _kb_bom_text(data)
+    nl = "\r\n" if "\r\n" in text else "\n"
+    lines = text.split(nl)
+    if not lines or lines[0].strip() != "---":
+        return None
+    end = next((i for i in range(1, min(len(lines), 60)) if lines[i].strip() == "---"),
+               None)
+    if end is None:
+        return None
+    inserted = ["imported_from: %s — %s" % (project, rel)]
+    origin = [i for i in range(1, end) if re.match(r"^origin:", lines[i], re.I)]
+    for i in origin:
+        lines[i] = "origin: imported"
+    if not origin:
+        inserted.append("origin: imported")
+    lines[1:1] = inserted
+    return bom + nl.join(lines).encode("utf-8"), len(inserted)
+
+
+def _kb_shift_loc(loc, k):
+    a, b = (int(x) for x in LOC_LINE_RE.match(loc).groups())
+    if a >= 2:
+        return "L%d-%d" % (a + k, b + k)
+    return "L1-%d" % (b + k if b >= 2 else 1)
+
+
+def _kb_span(data, loc):
+    """The lines a line locator addresses, minus the two lines an import may
+    insert or rewrite -- what a moved locator must still cite."""
+    a, b = (int(x) for x in LOC_LINE_RE.match(loc).groups())
+    return [x for x in _kb_bom_text(data)[1].splitlines()[a - 1:b]
+            if not re.match(r"^(imported_from|origin):", x, re.I)]
+
+
+def _kb_rewrite_derived_from(data, renames):
+    """A note whose derived_from names a renamed ruling note names the copy. The
+    edit stays on the derived_from line, so no line moves."""
+    bom, text = _kb_bom_text(data)
+    nl = "\r\n" if "\r\n" in text else "\n"
+    lines = text.split(nl)
+    if not lines or lines[0].strip() != "---":
+        return data
+    for i in range(1, min(len(lines), 60)):
+        if lines[i].strip() == "---":
+            break
+        m = re.match(r"^(derived_from:\s*)(.*)$", lines[i], re.I)
+        if not m:
+            continue
+        val = m.group(2).strip()
+        listed = val.startswith("[") and val.endswith("]")
+        toks = val[1:-1].split(",") if listed else [val]
+        out = []
+        for tok in toks:
+            e = kb_unquote(tok)
+            hit = next((new for old, new in renames.items()
+                        if e in (old, old[len("corpus/notes/"):])), None)
+            out.append((" " if listed and out else "") + hit if hit else tok)
+        new = ("[%s]" % ",".join(out)) if listed else out[0]
+        lines[i] = m.group(1) + new
+    return bom + nl.join(lines).encode("utf-8")
+
+
+def kb_import_foreign_rulings(bundle, docs, topic_rels, written, project):
+    """F-083 -- knowledge crosses a project boundary, authority does not
+    (portability.md §4, owner rulings 2026-08-03 and R3 of F-083).
+
+    -> (content, drop, report, errors). content: {rel: bytes} to write instead of
+    the bundle's bytes; drop: rels never to write (a ruling note under its own
+    name); report: {"converted": n, "notes": [renamed notes of skipped topics]}.
+
+    A RULING row arrives IMPORTED, resting on a renamed copy of its note that
+    names the origin; the rows it superseded and the ruling form one CONTESTED
+    set again. The note is never edited in place: a line inserted into it moves
+    the line every locator cites, and check verifies line bounds, not text."""
+    errors, content, drop = [], {}, set()
+    report = {"converted": 0, "notes": []}
+    slug = re.sub(r"[^a-z0-9]", "-", (project or "unknown").lower())
+    parsed = {}
+    for rel in topic_rels:
+        text = (bundle / rel).read_bytes().decode("utf-8")
+        parsed[rel] = (text, kb_parse_claims(text)[0])
+    rulings = [(rel, r) for rel in topic_rels for r in parsed[rel][1]
+               if r["prov"].strip().upper() == "RULING"]
+    # Which notes land foreign. A note cited by a RULING row is a ruling note;
+    # so is any bundle note declaring a basis: (reconciliation.md) -- one can
+    # travel without its row, cited by another row, and land first under its
+    # own name, ready to carry a local-looking RULING later (closure review B1).
+    users = {}                        # note -> [(topic rel, row)] RULING rows on it
+    for rel, r in rulings:
+        src = r["source"].split(";")[0].strip()
+        path, _, loc = src.rpartition("#")
+        if not (re.match(r"^corpus/notes/[^/]+\.md$", path) and LOC_LINE_RE.match(loc)
+                and (bundle / path).is_file()):
+            if rel in written:
+                errors.append("claim %s in %s is a RULING resting on %r, not on a "
+                              "note in corpus/notes/ cited by line (a ruling is a "
+                              "note, reconciliation.md) -- carry it by hand"
+                              % (r["id"] or "(no id)", rel, src))
+            continue
+        users.setdefault(path, []).append((rel, r))
+    ndir = bundle / "corpus" / "notes"
+    for p in (sorted(ndir.glob("*.md")) if ndir.is_dir() else []):
+        meta = sdlc_core.load_frontmatter(_kb_bom_text(p.read_bytes())[1].splitlines()) or {}
+        if meta.get("basis") and not meta.get("imported_from"):
+            users.setdefault("corpus/notes/" + p.name, [])
+    renames = {}                      # original note -> (copy, bytes, k)
+    for path in sorted(users):
+        data = (bundle / path).read_bytes()
+        meta = sdlc_core.load_frontmatter(_kb_bom_text(data)[1].splitlines()) or {}
+        ruled = [(rel, r) for rel, r in users[path] if rel in written]
+        where = ("claim %s in %s" % (ruled[0][1]["id"] or "(no id)", ruled[0][0])
+                 if ruled else path)
+        if meta.get("imported_from"):
+            if ruled:
+                errors.append("%s is a RULING on %s, which already names a foreign "
+                              "origin -- the source project relabelled an imported "
+                              "decision; fix it there" % (where, path))
+            continue                  # already foreign: it travels as it is
+        home = docs / path
+        if not ruled and home.is_file() and                 kb_sha256_bytes(home) == hashlib.sha256(data).hexdigest():
+            continue                  # this project holds the note, no topic here rules on it
+        foreign = _kb_foreign_note(data, project, path)
+        if foreign is None:
+            if ruled:
+                errors.append("%s rests on %s, which opens no frontmatter"
+                              % (where, path))
+            continue
+        copy = "corpus/notes/imported_%s_%s" % (slug, path[len("corpus/notes/"):])
+        if sdlc_core.confine_under(docs, copy) is None:
+            errors.append("renamed note %r escapes the docs root" % copy)
+            continue
+        renames[path] = (copy, foreign[0], foreign[1])
+    if errors:
+        return content, drop, report, errors
+    for old, (copy, data, _k) in renames.items():
+        drop.add(old)
+        content[copy] = data
+    for p in sorted((bundle / "corpus" / "notes").glob("*.md")) \
+            if (bundle / "corpus" / "notes").is_dir() else []:
+        rel = "corpus/notes/" + p.name
+        if rel in drop:
+            continue
+        new = _kb_rewrite_derived_from(p.read_bytes(),
+                                       dict((o, c) for o, (c, _d, _k) in renames.items()))
+        if new != p.read_bytes():
+            content[rel] = new
+    for copy in [c for c in list(content) if c in [v[0] for v in renames.values()]]:
+        content[copy] = _kb_rewrite_derived_from(
+            content[copy], dict((o, c) for o, (c, _d, _k) in renames.items()))
+
+    # rows of the topics this import writes: move sources, re-mint ids
+    ren, rows_w, prov_of = {}, [], {}
+    for rel in topic_rels:
+        if rel not in written:
+            continue
+        for r in parsed[rel][1]:
+            rows_w.append((rel, r))
+    for rel, r in rows_w:
+        cells = [s.strip() for s in r["source"].split(";") if s.strip()]
+        moved = []
+        for n, s in enumerate(cells):
+            path, _, loc = s.rpartition("#")
+            if path in renames and LOC_LINE_RE.match(loc):
+                copy, data, k = renames[path]
+                nloc = _kb_shift_loc(loc, k)
+                if _kb_span((bundle / path).read_bytes(), loc) != _kb_span(data, nloc):
+                    errors.append("claim %s in %s: %s#%s would not cite the same text "
+                                  "in %s#%s -- nothing was converted"
+                                  % (r["id"], rel, path, loc, copy, nloc))
+                cells[n] = "%s#%s" % (copy, nloc)
+                moved.append(n)
+            elif path in renames:
+                errors.append("claim %s in %s cites %s by %r, not by line: the "
+                              "renamed copy would move it" % (r["id"], rel, path, loc))
+        r["_source"] = "; ".join(cells) if moved else r["source"]
+        r["_id"] = r["id"]
+        if 0 in moved and r["id"]:
+            path, _, loc = cells[0].rpartition("#")
+            try:
+                r["_id"] = kb_claim_id(path, loc, kb_qty_key(r["qty"]))
+            except ValueError:
+                pass
+            ren[r["id"]] = r["_id"]
+        conv = r["prov"].strip().upper() == "RULING" and \
+            r["source"].split(";")[0].strip().rpartition("#")[0] in renames
+        r["_prov"] = "IMPORTED" if conv else r["prov"]
+        r["_conv"] = conv
+    if errors:
+        return content, drop, report, errors
+    converted = set(r["id"] for _rel, r in rows_w if r["_conv"])
+    report["converted"] = len(converted)
+    members = {}
+    for rel, r in rows_w:
+        kind, targets = _kb_states(r["state"])
+        hit = [t for t in targets if t in converted]
+        if kind != "SUPERSEDED" or not hit:
+            continue
+        if len(hit) != len(targets):
+            errors.append("claim %s in %s is SUPERSEDED by the ruling %s and by %s, "
+                          "which is not a ruling: its set cannot reopen without "
+                          "deciding which successor stands -- re-rule it in the "
+                          "source project" % (r["id"], rel, ", ".join(hit),
+                                              ", ".join(t for t in targets if t not in hit)))
+            continue
+        for t in hit:
+            members.setdefault(t, set()).add(r["id"])
+    partners = {}
+    for rel, r in rows_w:
+        if r["_conv"] and members.get(r["id"]):
+            kind, targets = _kb_states(r["state"])
+            if kind == "SUPERSEDED" and any(t not in converted for t in targets):
+                errors.append("ruling %s in %s settled rows but was itself superseded "
+                              "by %s, which is not a ruling: its set cannot reopen "
+                              "cleanly -- re-rule it in the source project"
+                              % (r["id"], rel, ", ".join(targets)))
+            group = members[r["id"]] | {r["id"]}
+            for x in group:
+                partners.setdefault(x, set()).update(group - {x})
+    if errors:
+        return content, drop, report, errors
+    for rel, r in rows_w:
+        kind, targets = _kb_states(r["state"])
+        if r["id"] in partners:
+            own = set(targets) if kind == "CONTESTED" else set()
+            r["_state"] = "CONTESTED " + ", ".join(
+                sorted(ren.get(t, t) for t in own | partners[r["id"]]))
+        elif kind:
+            r["_state"] = "%s %s" % (kind, ", ".join(ren.get(t, t) for t in targets))
+        else:
+            r["_state"] = r["state"]
+        prov_of[r["_id"]] = r["_prov"].strip().upper()
+
+    # boundary: every pointer must resolve after the import, never onto a foreign row
+    held = {}
+    for _slug, (_p, _t, trows) in kb_collect_topics(docs).items():
+        for t in trows:
+            if t["id"]:
+                held[t["id"]] = (t["prov"].strip().upper(), t["state"])
+    for rel, r in rows_w:
+        kind, targets = _kb_states(r["_state"])
+        for t in targets:
+            prov = prov_of.get(t) or (held.get(t) or (None,))[0]
+            if t not in prov_of and t in held and kind == "CONTESTED":
+                hkind, hts = _kb_states(held[t][1])
+                if hkind != "CONTESTED" or r["_id"] not in hts:
+                    errors.append("claim %s in %s is CONTESTED with %s, which this "
+                                  "project holds without naming it back: the import "
+                                  "never edits an existing topic -- add the pointer "
+                                  "there first, or carry the row by hand"
+                                  % (r["_id"], rel, t))
+                    continue
+            if prov is None:
+                errors.append("claim %s in %s points at %s, which this import does not "
+                              "write and this project does not hold: its set would "
+                              "arrive incomplete -- import the topics together"
+                              % (r["_id"], rel, t))
+            elif kind == "SUPERSEDED" and prov == "IMPORTED":
+                errors.append("claim %s in %s is SUPERSEDED by %s, which is IMPORTED "
+                              "here: a foreign decision cannot settle it -- import the "
+                              "topics together, or reopen the set by hand"
+                              % (r["_id"], rel, t))
+    if errors:
+        return content, drop, report, errors
+
+    for rel in topic_rels:
+        if rel not in written:
+            continue
+        text, rows = parsed[rel]
+        lines = text.split("\n")
+        for r in rows:
+            up = {}
+            for col, key in (("id", "_id"), ("source", "_source"), ("prov", "_prov"),
+                             ("state", "_state")):
+                if r[key] != r[col]:
+                    up[CLAIM_COLUMNS.index(col)] = r[key]
+            if up:
+                lines[r["_line"] - 1] = _kb_replace_cells(lines[r["_line"] - 1], up)
+        new = "\n".join(lines).encode("utf-8")
+        if new != (bundle / rel).read_bytes():
+            content[rel] = new
+    for rel, r in rulings:
+        path = r["source"].split(";")[0].strip().rpartition("#")[0]
+        if rel not in written and path in renames:
+            note = renames[path][0]
+            if note not in report["notes"]:
+                report["notes"].append(note)
+    return content, drop, report, errors
+
+
+def kb_import_plan(bundle, docs, report=None):
     """(writes, skipped_topics, dedup, errors) -- computed BEFORE anything is
     written, because an import that half-applies leaves a tree whose checks fail
-    and whose owner cannot tell what landed."""
+    and whose owner cannot tell what landed. Each write is (rel, bytes, dst):
+    the bytes are the bundle's, except where F-083 makes a foreign ruling land
+    foreign (kb_import_foreign_rulings). `report`, when a dict, receives what
+    that conversion did."""
     errors, writes, skipped, dedup = [], [], [], []
     man = bundle / BUNDLE_MANIFEST
     if not man.is_file():
@@ -1860,6 +2293,7 @@ def kb_import_plan(bundle, docs):
             if r["id"]:
                 known_ids.add(r["id"])
 
+    entries, topic_rels, written = [], [], set()
     for p in sorted(bundle.rglob("*")):
         if not p.is_file() or p.name == BUNDLE_MANIFEST:
             continue
@@ -1869,22 +2303,48 @@ def kb_import_plan(bundle, docs):
             errors.append("bundle entry %r escapes the docs root — refusing the "
                           "whole import, not just this file" % rel)
             continue
+        if rel.startswith("topics/"):
+            topic_rels.append(rel)
+            if dst.is_file():
+                skipped.append(rel)
+                continue
+            written.add(rel)
+        entries.append((rel, p, dst))
+    for rel, p, _dst in entries:
+        if rel.startswith("topics/"):
+            for r in kb_parse_claims(sdlc_core.read_text(p))[0]:
+                if _kb_is_declared(r):
+                    errors.append("%s: claim %s is DECLARED -- a declaration stays in "
+                                  "the project that made it; export never ships one, "
+                                  "so this bundle was edited by hand"
+                                  % (rel, r["id"] or "(no id)"))
+    if errors:
+        return [], skipped, [], errors
+
+    content, drop, rep, errors = kb_import_foreign_rulings(
+        bundle, docs, topic_rels, written, str(meta.get("source_project", "")).strip())
+    if report is not None:
+        report.update(rep)
+    if errors:
+        return [], skipped, [], errors
+    planned = [(rel, p, dst) for rel, p, dst in entries if rel not in drop]
+    for rel in sorted(set(content) - set(rel for rel, _p, _d in entries)):
+        planned.append((rel, None, sdlc_core.confine_under(docs, rel)))
+    for rel, p, dst in planned:
+        data = content[rel] if rel in content else p.read_bytes()
         if dst.is_file() and not rel.startswith("topics/"):
-            if kb_sha256_bytes(dst) != kb_sha256_bytes(p):
+            if kb_sha256_bytes(dst) != hashlib.sha256(data).hexdigest():
                 errors.append("%s exists with different bytes (target %s… vs "
                               "bundle %s…): content-addressed names must mean "
                               "equal content" % (rel, kb_sha256_bytes(dst)[:8],
-                                                 kb_sha256_bytes(p)[:8]))
+                                                 hashlib.sha256(data).hexdigest()[:8]))
             continue
-        if rel.startswith("topics/") and dst.is_file():
-            skipped.append(rel)
-            continue
-        writes.append((rel, p, dst))
+        writes.append((rel, data, dst))
 
-    for rel, p, _dst in writes:
+    for rel, data, _dst in writes:
         if not rel.startswith("topics/"):
             continue
-        rows, _ = kb_parse_claims(sdlc_core.read_text(p))
+        rows, _ = kb_parse_claims(data.decode("utf-8"))
         for r in rows:
             if r["id"] and r["id"] in known_ids:
                 dedup.append(r["id"])
@@ -2023,7 +2483,8 @@ def kb_validate_surface(docs, full=False):
     return rc
 
 INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id",
-               "anchor", "export", "import", "stale", "recall", "adopt"}
+               "anchor", "export", "import", "stale", "recall", "adopt",
+               "inventory"}
 
 
 def _kb_root(args):
@@ -2093,6 +2554,9 @@ def _kb_extra_validate(docs):
     """The kb additions to validate: generated-index freshness for the overlay's
     two indexes. Prints nothing on a tree without them (TS-K7)."""
     rc = 0
+    for e in kb_exclusions(docs)[1]:
+        print("[ERROR] %s" % e)
+        rc = 1
     checks = (("topics", kb_build_topic_index), ("corpus", kb_build_corpus_index))
     for dirname, builder in checks:
         idx = docs / dirname / "INDEX.md"
@@ -2185,6 +2649,391 @@ def kb_cmd_adopt(root, docs):
     return 0
 
 
+# --------------------------------------------------------------------------
+# F-084: the corpus's reach over the project that holds it. A file left out on
+# purpose and a file nobody opened used to look the same; these classify every
+# project file against the sidecars, by content, and name the residue.
+
+KB_REGISTRY = "audit/INVENTORY_exclusions.md"
+KB_REACH_DEADLINE = 1.0          # orient's walk; inventory has none (on demand)
+_kb_clock = time.monotonic       # injectable for the deadline test
+_KB_DATE_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})\b")
+# Windows: FILE_ATTRIBUTE_OFFLINE, RECALL_ON_OPEN, RECALL_ON_DATA_ACCESS;
+# macOS: SF_DATALESS. A file whose bytes are not on the disk is never read --
+# reading it would download it.
+_KB_CLOUD_ATTRS = 0x1000 | 0x40000 | 0x400000
+_KB_SF_DATALESS = 0x40000000
+_KB_REPARSE_POINT = 0x400
+
+
+class _KbDeadline(Exception):
+    pass
+
+
+def _kb_glob_regex(pattern):
+    """FS2's gitignore subset -> (compiled regex, dir_only)."""
+    dir_only = pattern.endswith("/")
+    pat = pattern.rstrip("/")
+    out, i = [], 0
+    while i < len(pat):
+        c = pat[i]
+        if pat.startswith("**/", i):
+            out.append("(?:[^/]+/)*")
+            i += 3
+        elif pat.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif c == "*":
+            out.append("[^/]*")
+            i += 1
+        elif c == "?":
+            out.append("[^/]")
+            i += 1
+        elif c == "[":
+            j = pat.find("]", i + 1)
+            if j < 0:
+                out.append(re.escape(c))
+                i += 1
+            else:
+                body = pat[i + 1:j]
+                if body.startswith("!"):
+                    body = "^" + body[1:]
+                out.append("[%s]" % body.replace("\\", "\\\\"))
+                i = j + 1
+        else:
+            out.append(re.escape(c))
+            i += 1
+    rx = "".join(out)
+    rx = ("^" + rx + "$") if "/" in pat else ("^(?:.*/)?" + rx + "$")
+    return re.compile(rx, re.IGNORECASE if os.name == "nt" else 0), dir_only
+
+
+def kb_exclusions(docs):
+    """(rows, errors) of the exclusion registry. rows: (pattern, regex,
+    dir_only). An absent registry excludes nothing and is silent."""
+    p = docs / KB_REGISTRY
+    rows, errors = [], []
+    if not p.is_file():
+        return rows, errors
+    import datetime as _dt
+    for n, line in enumerate(sdlc_core.read_text(p).splitlines(), 1):
+        s = line.strip()
+        if not s.startswith("|"):
+            continue
+        cells = [c.strip() for c in s.strip("|").split("|")]
+        joined = "".join(cells)
+        if "-" in joined and set(joined) <= set("-: "):
+            continue  # separator
+        if cells and cells[0].lower() == "pattern":
+            continue  # header
+        where = "%s:%d" % (KB_REGISTRY, n)
+        if len(cells) != 3:
+            errors.append("%s: a row has three cells: pattern | reason | approved" % where)
+            continue
+        pattern, reason, approved = cells
+        bad = []
+        if not pattern:
+            bad.append("empty pattern")
+        elif pattern.startswith("/") or ".." in pattern.split("/"):
+            bad.append("pattern %r leaves the project root" % pattern)
+        if not reason:
+            bad.append("empty reason -- say why it never enters the corpus")
+        m = _KB_DATE_RE.match(approved)
+        ok_date = False
+        if m:
+            try:
+                _dt.date(int(m.group(1)), int(m.group(2)), int(m.group(3)))
+                ok_date = True
+            except ValueError:
+                pass
+        if not ok_date:
+            bad.append("approved %r is not the day of the practitioner's approval "
+                       "(YYYY-MM-DD)" % approved)
+        rx = dir_only = None
+        if not bad:
+            try:
+                rx, dir_only = _kb_glob_regex(pattern)
+            except re.error as e:
+                bad.append("pattern %r is not a valid glob (%s)" % (pattern, e))
+        if bad:
+            errors.append("%s: %s" % (where, "; ".join(bad)))
+            continue
+        rows.append((pattern, rx, dir_only))
+    return rows, errors
+
+
+def kb_excluded(rel, is_dir, rows):
+    """The registry pattern matching project-relative `rel`, or None."""
+    for pattern, rx, dir_only in rows:
+        if dir_only and not is_dir:
+            continue
+        if rx.match(rel):
+            return pattern
+    return None
+
+
+def kb_unreadable(entry):
+    """'link' / 'cloud-only' for a DirEntry whose bytes are never read; None
+    otherwise. Links include Windows junctions (the `_memory_safe` idiom)."""
+    try:
+        if entry.is_symlink():
+            return "link"
+        is_junction = getattr(entry, "is_junction", None)
+        if is_junction is not None and is_junction():
+            return "link"
+        st = entry.stat(follow_symlinks=False)
+    except OSError:
+        return "unreadable"
+    attrs = getattr(st, "st_file_attributes", 0) or 0
+    if attrs & _KB_REPARSE_POINT and entry.is_dir(follow_symlinks=False):
+        return "link"  # a junction on a runtime without is_junction
+    if attrs & _KB_CLOUD_ATTRS or (getattr(st, "st_flags", 0) or 0) & _KB_SF_DATALESS:
+        return "cloud-only"
+    return None
+
+
+def _kb_path_key(p):
+    return os.path.normcase(os.path.abspath(str(p)))
+
+
+def _kb_reach_index(docs):
+    """What the sidecars say about originals: digest -> sidecar, named path ->
+    (sidecar, original_sha256 or None), the artifacts' sizes. Tombstones count
+    for nothing, their `original_path:` included."""
+    by_digest, by_path, sizes = {}, {}, set()
+    given = docs / "corpus" / "given"
+    if not given.is_dir():
+        return by_digest, by_path, sizes
+    for meta_p in sorted(given.glob("*.meta.md")):
+        meta = sdlc_core.load_frontmatter(sdlc_core.read_text(meta_p).splitlines()) or {}
+        if kb_is_tombstone(meta):
+            continue
+        rel = "corpus/given/" + meta_p.name
+        try:
+            sizes.add((given / meta_p.name[:-len(".meta.md")]).stat().st_size)
+        except OSError:
+            pass
+        for k in ("sha256", "original_sha256"):
+            v = (meta.get(k) or "").strip().lower()
+            if v:
+                by_digest.setdefault(v, rel)
+        op = kb_unquote(meta.get("original_path"))
+        if op:
+            osha = (meta.get("original_sha256") or "").strip().lower() or None
+            for c in _kb_original_candidates(op, docs):
+                try:
+                    present = c.is_symlink() or c.exists()
+                except OSError:
+                    present = False
+                if present:
+                    by_path.setdefault(_kb_path_key(c), (rel, osha))
+                    break
+    return by_digest, by_path, sizes
+
+
+def kb_corpus_reach(docs, rel=".", exact=True, deadline=None):
+    """FS1/FS3: classify the project files under `rel` (project-relative).
+
+    exact=True (inventory): every candidate is hashed -- comparison by content,
+    wherever the file now lives. exact=False (orient's bound): only files whose
+    size equals some given/ artifact's are hashed, and every file an
+    original_path names counts as examined, so the NOT_EXAMINED count never
+    undercounts. Returns {"entries": [(rel, STATE, basis)], "not_examined": n}.
+    Raises _KbDeadline when `deadline` seconds of walking pass.
+    """
+    project = docs.parent
+    rows, _errors = kb_exclusions(docs)
+    by_digest, by_path, sizes = _kb_reach_index(docs)
+    docs_key = _kb_path_key(docs)
+    entries, counter = [], [0]
+    start = _kb_clock()
+
+    def add(r, state, basis=""):
+        entries.append((r, state, basis))
+        if state == "NOT_EXAMINED":
+            counter[0] += 1
+
+    def visit(e, erel):
+        if deadline is not None and _kb_clock() - start > deadline:
+            raise _KbDeadline()
+        kind = kb_unreadable(e)
+        try:
+            # A link's target is never looked up (a dead network target would
+            # stall orient): a link is matched by its NAME, as if it were a
+            # directory, for the skip rule and dir-only exclusions.
+            dir_like = kind == "link" or e.is_dir(follow_symlinks=False)
+        except OSError:
+            dir_like = False
+        if dir_like and _kb_path_key(e.path) == docs_key:
+            return
+        if dir_like and sdlc_core.skip_dir(e.name):
+            add(erel + "/", "SKIPPED", "built-in rule")
+            return
+        pat = kb_excluded(erel, dir_like, rows)
+        if pat:
+            add(erel + "/" if dir_like else erel, "EXCLUDED", pat)
+            return
+        if kind is None and dir_like:
+            walk(e.path, erel)
+            return
+        if kind == "link":
+            dir_like = False
+        named = by_path.get(_kb_path_key(e.path))
+        if kind:
+            if named:
+                add(erel, "INGESTED", "%s, by path — not read" % named[0])
+            else:
+                add(erel, "NOT_EXAMINED", {"link": "link — not followed",
+                                           "cloud-only": "cloud-only — not read"}
+                    .get(kind, "unreadable — not read"))
+            return
+        if not e.is_file(follow_symlinks=False):
+            return
+        digest = None
+        try:
+            if exact or e.stat(follow_symlinks=False).st_size in sizes:
+                digest = kb_sha256_bytes(Path(e.path))
+        except OSError:
+            digest = None
+        if digest and digest in by_digest:
+            add(erel, "INGESTED", by_digest[digest])
+        elif named:
+            srel, osha = named
+            if osha is None:
+                add(erel, "INGESTED", "%s, by path — digest not kept" % srel)
+            elif not exact:
+                add(erel, "INGESTED", srel)       # examined; exactness is inventory's
+            else:
+                add(erel, "INGESTED_EARLIER", "%s, original changed since ingest" % srel)
+        else:
+            add(erel, "NOT_EXAMINED")
+
+    def walk(d, drel):
+        try:
+            with os.scandir(d) as it:
+                items = sorted(it, key=lambda x: x.name)
+        except OSError:
+            add((drel + "/") if drel else "./", "NOT_EXAMINED", "unreadable — not read")
+            return
+        for e in items:
+            visit(e, (drel + "/" + e.name) if drel else e.name)
+
+    rel = (rel or ".").replace("\\", "/").strip("/")
+    if rel in ("", "."):
+        walk(str(project), "")
+    else:
+        target = project / rel
+        with os.scandir(str(target.parent)) as it:
+            for e in it:
+                if os.path.normcase(e.name) == os.path.normcase(target.name):
+                    visit(e, rel)
+    entries.sort(key=lambda t: t[0])
+    return {"entries": entries, "not_examined": counter[0]}
+
+
+def kb_cmd_inventory(root, docs, path):
+    """FS3: one line per project file under `path`, in path order, with its
+    state. No totals, no filter, no sort by state (r37). Writes nothing."""
+    if not docs.is_dir():
+        print("[ERROR] no docs root")
+        return 1
+    project = docs.parent
+    rel = (path or "").replace("\\", "/").strip()
+    parts = [x for x in rel.split("/") if x not in ("", ".")]
+    if rel.startswith("/") or ntpath.isabs(rel) or ".." in parts:
+        print("[ERROR] %s is outside the project root" % path)
+        return 2
+    # Lexical, never resolved: a link on the way is not followed (FS1). Each
+    # component is matched to the name on disk, case-insensitively where the
+    # filesystem is, so a differently-cased path is never an empty listing.
+    real = []
+    for name in parts:
+        here = project.joinpath(*real)
+        try:
+            with os.scandir(str(here)) as it:
+                found = [e.name for e in it
+                         if os.path.normcase(e.name) == os.path.normcase(name)]
+        except OSError:
+            found = []
+        if not found:
+            print("[ERROR] %s does not exist" % path)
+            return 2
+        real.append(name if name in found else found[0])
+        if len(real) < len(parts) and (
+                os.path.islink(project.joinpath(*real))
+                or getattr(os.path, "isjunction", lambda _p: False)(project.joinpath(*real))):
+            print("[ERROR] %s lies behind %s, a link the inventory never follows"
+                  % (path, "/".join(real)))
+            return 2
+    parts = real
+    rows, _e = kb_exclusions(docs)
+    for i, name in enumerate(parts):
+        prefix = "/".join(parts[:i + 1])
+        here = project.joinpath(*parts[:i + 1])
+        if _kb_path_key(here) == _kb_path_key(docs):
+            print("[ERROR] %s is the docs root: the corpus is not a project-file area" % path)
+            return 2
+        dir_like = os.path.islink(here) or os.path.isdir(here)
+        if dir_like and sdlc_core.skip_dir(name):
+            print("[ERROR] %s lies in %s/, which the validator never treats as "
+                  "project files (built-in rule)" % (path, prefix))
+            return 2
+        if dir_like and kb_excluded(prefix, True, rows):
+            print("[ERROR] %s lies in %s/, excluded by %s" % (path, prefix, KB_REGISTRY))
+            return 2
+    reach = kb_corpus_reach(docs, "/".join(parts) or ".", exact=True)
+    for r, state, basis in reach["entries"]:
+        print(("%-16s  %s  %s" % (state, r, basis)).rstrip())
+    print("Nothing was written.")
+    return 0
+
+
+def kb_changed_originals(docs):
+    """FS5: [(artifact rel, original_path, n citing claims)] for every live,
+    non-superseded sidecar whose local original's bytes differ from the
+    `original_sha256:` it recorded at ingest."""
+    given = docs / "corpus" / "given"
+    if not given.is_dir():
+        return []
+    metas = []
+    superseded = set()
+    for meta_p in sorted(given.glob("*.meta.md")):
+        meta = sdlc_core.load_frontmatter(sdlc_core.read_text(meta_p).splitlines()) or {}
+        metas.append((meta_p, meta))
+        sup = kb_unquote(meta.get("supersedes"))
+        if sup:
+            superseded.add(sup)
+    cites = {}
+    for _slug, (_p, _t, rows) in kb_collect_topics(docs).items():
+        for r in rows:
+            for src in set(kb_claim_sources(r)):
+                cites[src] = cites.get(src, 0) + 1
+    out = []
+    for meta_p, meta in metas:
+        art = meta_p.name[:-len(".meta.md")]
+        if kb_is_tombstone(meta) or art in superseded:
+            continue
+        op = kb_unquote(meta.get("original_path"))
+        osha = (meta.get("original_sha256") or "").strip().lower()
+        if not (op and osha):
+            continue
+        for c in _kb_original_candidates(op, docs):
+            try:
+                if c.is_symlink() or not c.is_file():
+                    continue
+                st = os.lstat(str(c))  # attributes without opening the file
+                if (getattr(st, "st_file_attributes", 0) or 0) & _KB_CLOUD_ATTRS or \
+                        (getattr(st, "st_flags", 0) or 0) & _KB_SF_DATALESS:
+                    break
+                if kb_sha256_bytes(c) != osha:
+                    rel = "corpus/given/" + art
+                    out.append((rel, op, cites.get(rel, 0)))
+            except OSError:
+                pass
+            break
+    return out
+
+
 def kb_cmd_stale(root, docs, hybrid=False):
     """F-044: the consolidation view. The spine's output and exit semantics
     come first (--hybrid passed through untouched), then the `## claims`
@@ -2200,6 +3049,10 @@ def kb_cmd_stale(root, docs, hybrid=False):
                      % (topic_rel, rid, until,
                         ("cited by: " + ", ".join(by)) if by else "uncited"))
     lines += chain_w
+    for rel, op, n in kb_changed_originals(docs):
+        lines.append("%s: original %s changed since ingest -- %d claim(s) cite it; "
+                     "ingest the new version as a successor (supersedes:)"
+                     % (rel, op, n))
     if lines:
         print("")
         print("## claims")
@@ -2290,6 +3143,8 @@ def kb_cmd_export(args):
     if dropped:
         print("     not-yet-honored markers dropped: they describe this "
               "project's code")
+    if kb_has_declarations(selected):
+        print("     declarations stay in this project: not exported")
     if added:
         # never silent: a set that grew is a fact about the export, and the
         # alternative -- dropping the partner rows -- ships a broken tree.
@@ -2304,7 +3159,8 @@ def kb_cmd_import(args):
     if not bundle.is_dir():
         print("[ERROR] no such bundle directory: %s" % bundle)
         return 2
-    writes, skipped, dedup, errors = kb_import_plan(bundle, docs)
+    report = {}
+    writes, skipped, dedup, errors = kb_import_plan(bundle, docs, report)
     for e in errors:
         print("[ERROR] %s" % e)
     if errors:
@@ -2314,10 +3170,18 @@ def kb_cmd_import(args):
     if args.dry_run:
         print("[ok] dry run: %d file(s) would be written" % len(writes))
     else:
-        for _rel, src, dst in writes:
+        for _rel, data, dst in writes:
             dst.parent.mkdir(parents=True, exist_ok=True)
-            dst.write_bytes(src.read_bytes())
+            dst.write_bytes(data)
         print("[ok] imported %d file(s) into %s" % (len(writes), docs))
+    if report.get("converted"):
+        # portability.md §0 point 4: the agent must be able to tell the user
+        print("     %d ruling(s) arrive as IMPORTED: each rests on a renamed copy of "
+              "its note (imported_<project>_...) and settles nothing until you "
+              "ratify it (portability.md §4)" % report["converted"])
+    for note in report.get("notes", []):
+        print("[note] %s: a ruling of a skipped topic lands only as this foreign "
+              "copy -- a row merged by hand cites it as IMPORTED" % note)
     if dedup:
         print("     %d claim(s) already present, by id — the same artifact cited "
               "at the same span mints the same id in any project" % len(dedup))
@@ -2326,7 +3190,8 @@ def kb_cmd_import(args):
               "(taxonomy.md) and merge by hand — an import never decides that."
               % rel)
     print("[note] re-run 'sdlc_check.py check' now: the import is additive, and "
-          "an imported RULING stays IMPORTED until you re-ratify it.")
+          "an imported ruling stays IMPORTED until you ratify it with a note of "
+          "your own.")
     return 0
 
 
@@ -2512,6 +3377,23 @@ def _kb_orient_append(argv):
                           % (n_docs, m_exp, k_chain))
     except (Exception, SystemExit):
         pass
+    try:
+        # F-084: the corpus's reach, an upper bound of the project files never
+        # examined (R5). Its own try: a failing walk prints nothing and takes
+        # nothing else with it.
+        if root is not None and (root / name / "corpus").is_dir():
+            try:
+                n = kb_corpus_reach(root / name, ".", exact=False,
+                                    deadline=KB_REACH_DEADLINE)["not_examined"]
+            except _KbDeadline:
+                print("\nCorpus reach: not counted within 1s -- "
+                      "sdlc_check.py inventory <path>")
+            else:
+                if n:
+                    print("\nCorpus reach: <= %d project files not examined -- "
+                          "exact: sdlc_check.py inventory <path>" % n)
+    except (Exception, SystemExit):
+        pass
 
 
 def kb_cmd_help():
@@ -2541,6 +3423,10 @@ shared project memory -- also available:
   adopt                       dry run: document guides resting on .sources/
                               snapshots, and what moving them into corpus/given/
                               involves (writes nothing; portability.md par.6)
+  inventory <path>            the project files under <path> (. = all), each with
+                              its state against the corpus: INGESTED,
+                              INGESTED_EARLIER, EXCLUDED, NOT_EXAMINED (or
+                              SKIPPED); no totals, writes nothing
   remind                      one-line per-turn reminder (UserPromptSubmit hook,
                               opt-in -- ENFORCEMENT par.4; constant, zero-read)
 
@@ -2611,6 +3497,10 @@ def main(argv=None):
     p = sub.add_parser("adopt")
     p.add_argument("--root")
     p.add_argument("--docs-dir")
+    p = sub.add_parser("inventory")
+    p.add_argument("path")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
     args = ap.parse_args(argv)
     if args.cmd == "claim-id":
         return kb_cmd_claim_id(args)
@@ -2638,6 +3528,8 @@ def main(argv=None):
         return kb_cmd_corpus(docs, extra_errors=kb_credential_errors(root, docs))
     if args.cmd == "adopt":
         return kb_cmd_adopt(root, docs)
+    if args.cmd == "inventory":
+        return kb_cmd_inventory(root, docs, args.path)
     if args.cmd == "validate":
         return kb_cmd_validate(root, docs, strict=args.strict, hybrid=args.hybrid)
     return kb_cmd_check(root, docs, strict=args.strict, hybrid=args.hybrid)