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

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

@@ -5,12 +5,16 @@ 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
 import hashlib
 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
@@ -22,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}$")
@@ -112,6 +116,22 @@ def kb_claim_id(source_path, locator, qty_key=""):
 # reviewer-comment shape ("states X, that Y, and that Z").
 KB_BUNDLE_HINTS = (", and that ", "; ", ", while ", " and also ")
 
+# F-080: `about` holds relations joined by ';', and one reserved predicate whose
+# target is the Standalone ANALYSIS recording a deferred fix of code that does
+# not yet honor the claim. The mark has no reverse direction: nothing lists,
+# counts or selects claims by it -- only the claim checks and export read it.
+KB_NOT_HONORED = "not-yet-honored-by"
+KB_ABOUT_RE = re.compile(r"^([a-z0-9-]+) -> ([a-z0-9-]+)$")
+KB_NOT_HONORED_RE = re.compile(r"^%s -> ((?:ANALYSIS|SHADOW)_[A-Za-z0-9_-]+)$"
+                               % KB_NOT_HONORED)
+
+
+def kb_about_parts(cell):
+    """The ';'-joined parts of an `about` cell; [] for '-' or empty."""
+    if cell.strip() in ("", "-"):
+        return []
+    return [part.strip() for part in cell.split(";")]
+
 
 def kb_unquote(value):
     """Strip ONE pair of wrapping YAML quotes (then re-strip whitespace).
@@ -363,6 +383,7 @@ def kb_check_claims(root):
             src_cache[path_s] = (t, t is not None and t.is_file())
         return src_cache[path_s]
     per_file_rows = []
+    marked = []      # (where, row, [ANALYSIS_ targets]) -- F-080
     for p in sorted(topics.glob("*.md")):
         rel = "topics/" + p.name
         text = sdlc_core.read_text(p)
@@ -401,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"):
@@ -410,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"
@@ -429,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 "
@@ -445,11 +510,22 @@ def kb_check_claims(root):
             except ValueError as e:
                 errors.append("%s: %s" % (where, e))
                 qk = None
-            if row["about"] not in ("", "-"):
-                m = re.match(r"^([a-z0-9-]+) -> ([a-z0-9-]+)$", row["about"])
-                if not m:
-                    errors.append("%s: about must be '<predicate> -> <slug>' or '-'"
-                                  % where)
+            marks = []
+            for part in kb_about_parts(row["about"]):
+                mark = KB_NOT_HONORED_RE.match(part)
+                rel_m = KB_ABOUT_RE.match(part)
+                if mark:
+                    marks.append(mark.group(1))
+                elif part.split(" -> ")[0].strip() == KB_NOT_HONORED:
+                    errors.append("%s: about %r: '%s' needs an ANALYSIS_<name> "
+                                  "target (Hybrid: SHADOW_<doc_key>, unversioned) -- the "
+                                  "analysis or design that records the deferred "
+                                  "fix" % (where, part, KB_NOT_HONORED))
+                elif not rel_m:
+                    errors.append("%s: about must be '<predicate> -> <slug>' "
+                                  "parts joined by ';', or '-': %r" % (where, part))
+            if marks:
+                marked.append((where, row, marks))
             # --- atomicity hint (F-047): a row atomic as provenance can be
             # plural as meaning. Text cannot PROVE plurality, so this is a
             # note — never a warning or an error, never the exit code.
@@ -541,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:
@@ -556,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 — "
@@ -579,9 +680,123 @@ def kb_check_claims(root):
                                       "name %s back; one flipped cell must never "
                                       "silently end a disagreement"
                                       % (where, t, row["id"]))
+    kb_check_marks(root, marked, per_file_rows, errors)
     return errors, warnings, notes
 
 
+def kb_check_marks(root, marked, per_file_rows, errors):
+    """F-080: each not-yet-honored mark names an ANALYSIS that exists in this
+    project and cites the claim id -- or the id of a row this claim succeeds,
+    since supersession copies the mark and edits no analysis. F-081: a Hybrid
+    mark names SHADOW_<doc_key>, and the newest shadow of that key is read."""
+    if not marked:
+        return
+    preds = {}       # successor id -> ids it supersedes
+    for _, rows in per_file_rows:
+        for row in rows:
+            m = re.match(r"^SUPERSEDED ([0-9a-f, ]+)$", row["state"])
+            if row["id"] and m:
+                for t in [x.strip() for x in m.group(1).split(",") if x.strip()]:
+                    preds.setdefault(t, set()).add(row["id"])
+    texts = {}
+    for where, row, targets in marked:
+        ids, todo = set(), [row["id"]] if row["id"] else []
+        while todo:
+            cid = todo.pop()
+            if cid not in ids:
+                ids.add(cid)
+                todo.extend(preds.get(cid, ()))
+        for target in targets:
+            if target not in texts:
+                texts[target] = _kb_mark_target(root, target)
+            rel, text, stray = texts[target]
+            if text is None and target.startswith("SHADOW_"):
+                errors.append("%s: %s -> %s: no %s in this project%s. Export the "
+                              "shadow from the accepted devPNT version, or remove "
+                              "the marker if it did not come from this project -- "
+                              "it describes its origin's code"
+                              % (where, KB_NOT_HONORED, target, rel,
+                                 " (%s is not named _vX.Y)" % stray if stray else ""))
+            elif text is None:
+                errors.append("%s: %s -> %s: no %s in this project. Remove the "
+                              "marker if it did not come from this project -- it "
+                              "describes its origin's code" % (where, KB_NOT_HONORED,
+                                                              target, rel))
+            elif ids and not any(re.search(r"(?<![0-9a-f])%s(?![0-9a-f])" % cid, text)
+                                 for cid in ids):
+                errors.append("%s: %s does not cite claim %s -- the analysis or "
+                              "design that records a deferred fix cites the id it "
+                              "defers"
+                              % (where, rel, row["id"]))
+
+
+def _kb_mark_target(root, target):
+    """(rel, text or None, stray name or None) for a marker target. ANALYSIS_x
+    is solutions/x.md; SHADOW_k is the newest solutions/SHADOW_k_vX.Y.md, and
+    when none exists a file of the same exact key with another suffix is
+    reported as the stray that was not read (F-081)."""
+    if not target.startswith("SHADOW_"):
+        rel = "solutions/%s.md" % target
+        path = sdlc_core.confine_under(root, rel)
+        return rel, (sdlc_core.read_text(path)
+                     if path is not None and path.is_file() else None), None
+    key = target[len("SHADOW_"):]
+    sol = sdlc_core.confine_under(root, "solutions")
+    path = sdlc_core.newest_shadow(sol, key) if sol is not None else None
+    if path is not None and sdlc_core.confine_under(root, "solutions/" + path.name):
+        return "solutions/" + path.name, sdlc_core.read_text(path), None
+    stray = sdlc_core.stray_shadow(sol, key) if sol is not None else None
+    return "solutions/SHADOW_%s_v<X.Y>.md" % key, None, stray
+
+
+def kb_drop_marks(text):
+    """(text, dropped): the topic text with every not-yet-honored part removed
+    from claim rows' `about` cells. Every other byte is kept -- other cells keep
+    their spacing, other lines are untouched (F-080: a bundle describes no code)."""
+    rows, _ = kb_parse_claims(text)
+    lines = text.split("\n")
+    col = 1 + CLAIM_COLUMNS.index("about")
+    dropped = False
+    for row in rows:
+        parts = kb_about_parts(row["about"])
+        keep = [p for p in parts if not KB_NOT_HONORED_RE.match(p)]
+        if len(keep) == len(parts):
+            continue
+        # The parser strips the pipes at both ends, so a row with no trailing
+        # pipe is legal: counted from the left, the about cell sits at `col`
+        # either way.
+        segs = lines[row["_line"] - 1].split("|")
+        if len(segs) not in (len(CLAIM_COLUMNS) + 1, len(CLAIM_COLUMNS) + 2):
+            continue
+        segs[col] = " %s " % ("; ".join(keep) or "-")
+        lines[row["_line"] - 1] = "|".join(segs)
+        dropped = True
+    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.
 
@@ -912,6 +1127,10 @@ def kb_build_corpus_index(root):
         for meta_p in sorted(given.glob("*.meta.md")):
             meta = sdlc_core.load_frontmatter(sdlc_core.read_text(meta_p).splitlines()) or {}
             orig = meta_p.name[:-len(".meta.md")]
+            if kb_is_tombstone(meta):
+                lines.append("- `%s` — %s — withdrawn" % (
+                    orig, (meta.get("date") or "undated")))
+                continue
             sup = kb_unquote(meta.get("supersedes"))
             lines.append("- `%s` — %s%s — %s" % (
                 orig, (meta.get("date") or "undated"),
@@ -1056,6 +1275,21 @@ def kb_corpus_check(root):
             meta = sdlc_core.load_frontmatter(sdlc_core.read_text(meta_p).splitlines()) or {}
             orig = given / meta_p.name[:-len(".meta.md")]
             rel = "corpus/given/" + orig.name
+            if kb_is_tombstone(meta):
+                # F-077: a withdrawn artifact keeps its record, never its bytes
+                # nor a digest of them -- a digest of the secret-bearing bytes
+                # beside a redacted successor tests password guesses offline.
+                kept = [k for k in ("sha256", "original_sha256")
+                        if (meta.get(k) or "").strip()]
+                if kept:
+                    errors.append("%s: withdrawn, yet its sidecar keeps %s -- "
+                                  "a tombstone keeps no digest of the withdrawn "
+                                  "bytes (distillation.md par.1)"
+                                  % (rel, ", ".join(k + ":" for k in kept)))
+                if orig.is_file():
+                    errors.append("%s: withdrawn, yet its bytes are still here -- "
+                                  "delete them" % rel)
+                continue
             if not orig.is_file():
                 errors.append("%s: sidecar exists but the original is gone" % rel)
                 continue
@@ -1082,17 +1316,36 @@ def kb_corpus_check(root):
                         "extraction is intact, the pointer to the original is "
                         "not. A warning and not an error: a bundle carries "
                         "artifacts and sidecars, never the originals, so after "
-                        "an import this dangles legitimately"
-                        % (rel, op, ", ".join(tried)))
+                        "an import this dangles legitimately%s"
+                        % (rel, _kb_mask_userinfo(op),
+                           _kb_mask_userinfo(", ".join(tried)),
+                           " -- a non-local identifier belongs in original_ref:, "
+                           "which is recorded and never resolved"
+                           if re.match(r"^[A-Za-z][A-Za-z0-9+.\-]+://", op) else ""))
             sup = kb_unquote(meta.get("supersedes"))
             if sup:
                 superseded.add(sup)
-                if not (given / sup).is_file():
+                sup_side = given / (sup + ".meta.md")
+                tomb = sup_side.is_file() and kb_is_tombstone(
+                    sdlc_core.load_frontmatter(sdlc_core.read_text(sup_side).splitlines()))
+                if not (given / sup).is_file() and not tomb:
                     warnings.append("%s: supersedes %r which is not in given/"
                                     % (rel, sup))
             kb_check_coverage(rel, orig,
                               (meta.get("extracted_through") or "").strip(),
                               _kb_cited_for(cited, orig.name), errors, warnings)
+        # F-077: a file nobody declared -- or bytes a withdrawal left behind. A
+        # stored extraction `<stem>.txt` beside a declared `<stem>.<ext>` is the
+        # declared artifact's own (distillation.md par.1), not a stray.
+        declared_stems = set(Path(m.name[:-len(".meta.md")]).stem
+                             for m in given.glob("*.meta.md"))
+        for p in sorted(given.iterdir()):
+            if (p.is_file() and not p.name.endswith(".meta.md")
+                    and not (given / (p.name + ".meta.md")).is_file()
+                    and not (p.suffix == ".txt" and p.stem in declared_stems)):
+                warnings.append("corpus/given/%s: no sidecar -- an artifact nobody "
+                                "declared, or bytes a withdrawal left behind" % p.name)
+        warnings.extend(_kb_same_text_warnings(root))
     notes = corpus / "notes"
     if notes.is_dir():
         for p in sorted(notes.glob("*.md")):
@@ -1110,6 +1363,226 @@ def kb_corpus_check(root):
     return errors, warnings
 
 
+# ------------------------------------------------- credentials (F-077)
+# A credential stored in given/ cannot be fixed in place: the digest check
+# refuses the edit and git keeps the bytes. These shapes are written from the
+# formats' own syntax (key=value lines, PEM headers, URL userinfo, bearer
+# headers); no vendor key format is matched (distillation.md par.1 lists the
+# declared false positives and false negatives). Findings carry line numbers
+# and kinds, NEVER the value: the validator's output lands in logs and CI.
+
+KB_CRED_PAIRS = {("api", "key"): "api-key", ("access", "key"): "access-key",
+                 ("private", "key"): "private-key",
+                 ("client", "secret"): "client-secret", ("secret", "key"): "secret"}
+KB_CRED_LAST = {"password": "password", "passwd": "password",
+                "passphrase": "password", "secret": "secret", "token": "token",
+                "credential": "credentials", "credentials": "credentials",
+                "apikey": "api-key", "accesskey": "access-key"}
+KB_CRED_ASSIGN_RE = re.compile(
+    r"""^\s*(?:export\s+)?(["']?)([A-Za-z0-9_.\-]+)\1\s*[=:]\s*(.*)$""")
+KB_CRED_SEGMENT_RE = re.compile(r"[A-Z]?[a-z0-9]+|[A-Z]+(?![a-z])")
+KB_CRED_PEM_RE = re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")
+KB_CRED_URL_RE = re.compile(r"[A-Za-z][A-Za-z0-9+.\-]*://[^/\s:@]*:([^@\s/]+)@")
+KB_CRED_QUERY_RE = re.compile(r"[?&;](?:password|pwd|passwd)=([^&\s;#]+)", re.I)
+KB_CRED_BEARER_RE = re.compile(r"\bBearer\s+[A-Za-z0-9\-._~+/]{16,}")
+KB_CRED_PLACEHOLDER_RE = re.compile(
+    r"<.*>|\$\{.*\}|\{\{.*\}\}|%\(.*\)s|ENC\(.*\)|[*xX]+|[|>][-+]?\d*")
+KB_CRED_LINE_MAX = 4096
+KB_REVIEWED_RE = re.compile(r"^reviewed\s*[-—–:]\s*\S")
+
+
+def _kb_cred_real(value):
+    """True when a value looks like an actual secret, not a placeholder."""
+    v = re.split(r"\s+(?:#|//)", value.strip(), maxsplit=1)[0].strip()
+    if v.endswith(","):
+        v = v[:-1].rstrip()
+    if len(v) >= 2 and v[0] in "\"'" and v[-1] == v[0]:
+        v = v[1:-1]
+    if not v or re.search(r"\s", v):
+        return False
+    if v.lower() in ("true", "false", "null", "none", "yes", "no"):
+        return False
+    if v.startswith("[REDACTED") or KB_CRED_PLACEHOLDER_RE.fullmatch(v):
+        return False
+    return True
+
+
+def _kb_cred_key_kind(key):
+    segs = [s.lower() for part in re.split(r"[_.\-]", key)
+            for s in KB_CRED_SEGMENT_RE.findall(part)]
+    if len(segs) >= 2 and tuple(segs[-2:]) in KB_CRED_PAIRS:
+        return KB_CRED_PAIRS[tuple(segs[-2:])]
+    return KB_CRED_LAST.get(segs[-1]) if segs else None
+
+
+def kb_credential_line_kind(line):
+    """The credential kind one line carries, or None. Never returns the value."""
+    line = line[:KB_CRED_LINE_MAX]
+    if KB_CRED_PEM_RE.search(line):
+        return "private-key"
+    m = KB_CRED_ASSIGN_RE.match(line)
+    if m:
+        kind = _kb_cred_key_kind(m.group(2))
+        if kind and _kb_cred_real(m.group(3)):
+            return kind
+    m = KB_CRED_URL_RE.search(line)
+    if m and _kb_cred_real(m.group(1)):
+        return "connection-string"
+    m = KB_CRED_QUERY_RE.search(line)
+    if m and _kb_cred_real(m.group(1)):
+        return "connection-string"
+    if KB_CRED_BEARER_RE.search(line):
+        return "bearer-token"
+    return None
+
+
+def kb_credential_findings(path):
+    """[(line_no, kind)] for one file; [] for a binary or unreadable one.
+
+    A NUL in the first 8 KB means binary, unless the file opens with a UTF-16
+    byte-order mark (then it is decoded whole). Text is streamed line by line,
+    each inspected on its first KB_CRED_LINE_MAX characters."""
+    out = []
+    try:
+        with open(path, "rb") as f:
+            head = f.read(8192)
+        if head[:2] in (b"\xff\xfe", b"\xfe\xff"):
+            lines = Path(path).read_bytes().decode("utf-16", errors="replace").splitlines()
+            for n, line in enumerate(lines, 1):
+                kind = kb_credential_line_kind(line)
+                if kind:
+                    out.append((n, kind))
+            return out
+        if b"\x00" in head:
+            return []
+        with open(path, encoding="utf-8-sig", errors="replace") as f:
+            for n, line in enumerate(f, 1):
+                kind = kb_credential_line_kind(line.rstrip("\r\n"))
+                if kind:
+                    out.append((n, kind))
+    except OSError:
+        return []
+    return out
+
+
+def _kb_mask_userinfo(text):
+    """A password inside a URL never reaches the validator's output -- also once
+    a candidate path has turned its `//` into `\\` (Windows join)."""
+    return re.sub(r"([/\\][^/\\\s:@]*:)\S*@", r"\1***@", text)
+
+
+def _kb_reviewed(meta):
+    return bool(KB_REVIEWED_RE.match(kb_unquote((meta or {}).get("credential_scan"))))
+
+
+def _kb_cred_message(rel, found, fix):
+    nums = [str(n) for n, _ in found[:10]] + (["..."] if len(found) > 10 else [])
+    kinds = sorted(set(k for _, k in found))
+    return "%s: %s %s look like a credential (%s) -- %s" % (
+        rel, "line" if len(found) == 1 else "lines", ", ".join(nums),
+        ", ".join(kinds), fix)
+
+
+def kb_is_tombstone(meta):
+    return bool(kb_unquote((meta or {}).get("withdrawn")))
+
+
+def kb_credential_errors(root, docs):
+    """FS2 errors over given/ artifacts and document-guide snapshots, escapes
+    applied. One carrier per command calls this (check, corpus); validate never."""
+    errors = []
+    given = docs / "corpus" / "given"
+    if given.is_dir():
+        # A stored extraction `<stem>.txt` has no sidecar of its own: it is the
+        # declared `<stem>.<ext>`'s (distillation.md par.1), so its escape lives there.
+        by_stem = {}
+        for m in sorted(given.glob("*.meta.md")):
+            by_stem.setdefault(Path(m.name[:-len(".meta.md")]).stem, m)
+        for p in sorted(given.iterdir()):
+            if not p.is_file() or p.name.endswith(".meta.md"):
+                continue
+            side = given / (p.name + ".meta.md")
+            if not side.is_file() and p.suffix == ".txt" and p.stem in by_stem:
+                side = by_stem[p.stem]
+            meta = (sdlc_core.load_frontmatter(sdlc_core.read_text(side).splitlines())
+                    or {}) if side.is_file() else {}
+            if _kb_reviewed(meta):
+                continue
+            found = kb_credential_findings(p)
+            if found:
+                errors.append(_kb_cred_message(
+                    "corpus/given/" + p.name, found,
+                    "given/ is never edited: redact into a successor and withdraw "
+                    "this one (distillation.md par.1), or declare "
+                    "`credential_scan: reviewed -- <reason>` in its sidecar"))
+    for rel, _p, meta, _t in sdlc_core.list_guides(root):
+        if (meta.get("source_kind") or "document").strip() != "document":
+            continue
+        df = (meta.get("distilled_from") or "").strip()
+        src = sdlc_core.confine_under(root, df) if df else None
+        if src is None or not src.is_file() or _kb_reviewed(meta):
+            continue
+        try:
+            src.resolve().relative_to(given.resolve())
+            continue  # scanned above, once
+        except (OSError, ValueError):
+            pass
+        found = kb_credential_findings(src)
+        if found:
+            errors.append(_kb_cred_message(
+                df, found,
+                "redact into a new snapshot (its name changes) and update %s's "
+                "distilled_from, source_hash and markers, or declare "
+                "`credential_scan: reviewed -- <reason>` in the guide" % rel))
+    return errors
+
+
+def _kb_print_credentials(root, docs):
+    errs = kb_credential_errors(root, docs)
+    for e in errs:
+        print("[ERROR] %s" % e)
+    return 1 if errs else 0
+
+
+def _kb_same_text_warnings(docs):
+    """FS6: a .sources/ file and a given/ artifact holding the same text after
+    line-ending normalization. Snapshots are hashed once; a given/ artifact is
+    hashed only when its size is within a factor of two of some snapshot's (CRLF
+    at most doubles a text), so a large extraction corpus is not read for this."""
+    src = docs / "reference" / ".sources"
+    given = docs / "corpus" / "given"
+    if not (src.is_dir() and given.is_dir()):
+        return []
+    snaps = {}
+    sizes = []
+    for p in sorted(src.rglob("*")):
+        if p.is_file():
+            try:
+                snaps.setdefault(sdlc_core.sha256_file(p), []).append(p)
+                sizes.append(p.stat().st_size)
+            except OSError:
+                continue
+    if not snaps:
+        return []
+    lo, hi = min(sizes) // 2, max(sizes) * 2
+    out = []
+    for g in sorted(given.iterdir()):
+        if not g.is_file() or g.name.endswith(".meta.md"):
+            continue
+        try:
+            if not lo <= g.stat().st_size <= hi:
+                continue
+            h = sdlc_core.sha256_file(g)
+        except OSError:
+            continue
+        for s in snaps.get(h, []):
+            out.append("reference/.sources/%s and corpus/given/%s hold the same text "
+                       "-- one home per source text: re-point the guide to "
+                       "corpus/given/ (portability.md par.6, kb-agentic)"
+                       % (s.relative_to(src).as_posix(), g.name))
+    return out
+
+
 def kb_sha256_bytes(path):
     """RAW-byte digest for binaries. The spine's sha256_file normalizes CRLF->LF
     (right for text snapshots, wrong for binaries, where a hostile 0D0A/0A pair
@@ -1394,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))
@@ -1420,11 +1901,17 @@ 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):
                     if cand in seen:
                         continue
+                    if cand.endswith(".meta.md") and (docs / cand).is_file() and \
+                            kb_is_tombstone(sdlc_core.load_frontmatter(
+                                sdlc_core.read_text(docs / cand).splitlines())):
+                        continue  # F-077: a tombstone never travels
                     if (docs / cand).is_file():
                         seen.add(cand)
                         artifacts.append(cand)
@@ -1432,10 +1919,16 @@ def kb_export_closure(docs, slugs):
 
 
 def kb_bundle_write(docs, out, selected, artifacts, project):
-    """Write the bundle. Mirrors the docs-root layout; no path is rewritten."""
+    """Write the bundle. Mirrors the docs-root layout; no path is rewritten.
+    Returns whether a not-yet-honored mark was dropped (F-080) -- a yes/no,
+    never a count: a count of dropped marks is a count of claims by the mark."""
     out.mkdir(parents=True, exist_ok=True)
     (out / "topics").mkdir(exist_ok=True)
+    dropped = False
     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
@@ -1450,12 +1943,341 @@ def kb_bundle_write(docs, out, selected, artifacts, project):
     for rel in artifacts:
         lines.append("- `%s` sha256:%s" % (rel, kb_sha256_bytes(docs / rel)))
     (out / BUNDLE_MANIFEST).write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return dropped
+
+
+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
 
-
-def kb_import_plan(bundle, docs):
+    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():
@@ -1471,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
@@ -1480,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]))
-            continue
-        if rel.startswith("topics/") and dst.is_file():
-            skipped.append(rel)
+                                                 hashlib.sha256(data).hexdigest()[:8]))
             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"])
@@ -1622,15 +2471,20 @@ def kb_refresh_indexes(docs):
 
 
 def kb_validate_surface(docs, full=False):
-    """Additive seam for marketing: preserve its own validator and report."""
+    """Additive seam for marketing: preserve its own validator and report.
+    `full` is marketing's check: the credential scan (F-077) runs there outside
+    the topics/corpus guard, since document-guide snapshots need no corpus."""
     rc = max(memory_validate(docs), _kb_extra_validate(docs))
+    if full:
+        rc = max(rc, _kb_print_credentials(docs.parent, docs))
     if full and ((docs / "topics").is_dir() or (docs / "corpus").is_dir()):
         cycle = kb_time_cycle(docs)
         rc = max(rc, kb_cmd_graph(docs, cycle), kb_cmd_corpus(docs, cycle))
     return rc
 
 INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id",
-               "anchor", "export", "import", "stale", "recall"}
+               "anchor", "export", "import", "stale", "recall", "adopt",
+               "inventory"}
 
 
 def _kb_root(args):
@@ -1670,8 +2524,9 @@ def kb_cmd_graph(docs, cycle=None):
     return 0
 
 
-def kb_cmd_corpus(docs, cycle=None):
+def kb_cmd_corpus(docs, cycle=None, extra_errors=()):
     errors, warnings = kb_corpus_check(docs)
+    errors = list(extra_errors) + errors
     if cycle is None:
         cycle = kb_time_cycle(docs)
     _tc_cited, tc_chain, tc_dang = kb_time_cycle_warns(cycle)
@@ -1699,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"
@@ -1728,10 +2586,454 @@ def kb_cmd_check(root, docs, strict=False, hybrid=False):
                     ("corpus", lambda: kb_cmd_corpus(docs, cycle)))
     return sdlc_core.cmd_check(
         root, strict=strict, hybrid=hybrid,
-        extra_validate=lambda: max(_kb_extra_validate(docs), memory_validate(docs)),
+        extra_validate=lambda: max(_kb_extra_validate(docs), memory_validate(docs),
+                                   _kb_print_credentials(root, docs)),
         extra_sections=sections)
 
 
+def kb_cmd_adopt(root, docs):
+    """F-077: the dry-run plan of adopting kb-agentic on an existing docs root --
+    which document guides rest on a snapshot, and what moving each into
+    corpus/given/ involves. Reads only; there is no --apply (portability.md
+    par.6: the choice of source and the redaction are judgements)."""
+    if not docs.is_dir():
+        print("[ERROR] no docs root at %s" % docs)
+        return 1
+    given = docs / "corpus" / "given"
+    twins = {}
+    if given.is_dir():
+        for g in sorted(given.iterdir()):
+            if g.is_file() and not g.name.endswith(".meta.md"):
+                try:
+                    twins.setdefault(sdlc_core.sha256_file(g), g.name)
+                except OSError:
+                    pass
+    print("=== adopt: document guides -> corpus/given/ (dry run) ===")
+    code_n = 0
+    for rel, _p, meta, _t in sdlc_core.list_guides(root):
+        if (meta.get("source_kind") or "document").strip() != "document":
+            code_n += 1
+            continue
+        df = (meta.get("distilled_from") or "").strip()
+        print("%s" % rel)
+        print("  distilled_from: %s" % (df or "(none)"))
+        src = sdlc_core.confine_under(root, df) if df else None
+        if df and src is None:
+            print("  source: outside the project root -- not read")
+            continue
+        if src is None or not src.is_file():
+            print("  source: missing")
+            continue
+        try:
+            where = "/" + src.relative_to(root.resolve()).as_posix()
+        except ValueError:
+            where = ""
+        if "/corpus/given/" in where:
+            print("  source: already in corpus/given/")
+            continue
+        print("  source: %s" % (".sources/ snapshot" if "/reference/.sources/" in where
+                                 else "elsewhere"))
+        try:
+            twin = twins.get(sdlc_core.sha256_file(src))
+        except OSError:
+            twin = None
+        if twin:
+            print("  same text already in corpus/given/%s" % twin)
+        found = kb_credential_findings(src)
+        if found:
+            print("  " + _kb_cred_message("credential-shaped", found,
+                                         "redact before storing (distillation.md par.1)")
+                  .split(": ", 1)[1])
+    print("%d code guide(s) stay on .sources/." % code_n)
+    print("Nothing was written. Procedure: portability.md par.6 (kb-agentic).")
+    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`
@@ -1747,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")
@@ -1831,9 +3137,14 @@ def kb_cmd_export(args):
     if errors:
         return 1
     out = Path(args.out)
-    kb_bundle_write(docs, out, selected, artifacts, root.name)
+    dropped = kb_bundle_write(docs, out, selected, artifacts, root.name)
     print("[ok] bundle written: %s" % out)
     print("     topics: %d, artifacts: %d" % (len(selected), len(artifacts)))
+    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.
@@ -1848,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:
@@ -1858,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))
@@ -1870,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
 
 
@@ -1886,11 +3207,50 @@ def kb_cmd_orient(argv):
     needs to locate topics/, and ignores everything else.
 
     The append fails open: a broken graph read must never break orient itself.
+    It is also bounded (F-075): the spine leaves ORIENT_APPEND_RESERVE of the
+    client's hook cap free, and the append is cut to it -- the topic router
+    first, since it is the part that grows -- so the whole output stays under
+    the cap.
     """
     try:
         rc = sdlc_core.main(argv)
     except SystemExit as e:
         rc = e.code if isinstance(e.code, int) else 1
+    buf = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(buf):
+            _kb_orient_append(argv)
+    except (Exception, SystemExit):
+        pass
+    text = buf.getvalue()
+    if text:
+        print(_fit_orient_append(text, sdlc_core.ORIENT_APPEND_RESERVE), end="")
+    return rc
+
+
+def _fit_orient_append(text, budget):
+    """`text` within `budget` characters: shrink the topic-router block first,
+    then, if the rest alone is too wide, cut the whole append. Never raises."""
+    if len(text) <= budget:
+        return text
+    lines = text.rstrip("\n").split("\n")
+    try:
+        i = lines.index("## Topic router")
+        j = next((k for k in range(i + 1, len(lines)) if not lines[k].strip()), len(lines))
+        block, others = lines[i + 1:j], lines[:i + 1] + lines[j:]
+        room = budget - len("\n".join(others)) - 2
+        if room > 0:
+            fitted = sdlc_core.orient_fit(block, room, "topics/INDEX.md")
+            out = "\n".join(lines[:i + 1] + fitted + lines[j:]) + "\n"
+            if len(out) <= budget:
+                return out
+    except ValueError:
+        pass
+    return "\n".join(sdlc_core.orient_fit(lines, budget - 1, "the knowledge layer's files")) + "\n"
+
+
+def _kb_orient_append(argv):
+    """The lines kb_cmd_orient appends after the spine's orientation."""
     # Pre-bind so a throw INSIDE the router print (after root was validly
     # bound) does not erase it -- the recency block below must survive a
     # router failure with the bound root intact (closure R2 finding).
@@ -1944,7 +3304,7 @@ def kb_cmd_orient(argv):
         # skill's own worktree hygiene makes that routine), which is why the
         # frontmatter date is primary.
         if root is None:
-            return rc
+            return
         notes_dir = root / name / "corpus" / "notes"
         if notes_dir.is_dir():
             import datetime as _dt
@@ -2017,7 +3377,23 @@ def kb_cmd_orient(argv):
                           % (n_docs, m_exp, k_chain))
     except (Exception, SystemExit):
         pass
-    return rc
+    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():
@@ -2044,6 +3420,13 @@ shared project memory -- also available:
   anchor <path> <phrase>      resolve a phrase to a verified locator span
   export --out <dir>          bundle a subgraph WITH the bytes its claims cite
   import <dir>                merge a bundle in additively (never overwrites)
+  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)
 
@@ -2111,6 +3494,13 @@ def main(argv=None):
     p.add_argument("--dry-run", action="store_true")
     p.add_argument("--root")
     p.add_argument("--docs-dir")
+    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)
@@ -2135,7 +3525,11 @@ def main(argv=None):
     if args.cmd == "graph":
         return kb_cmd_graph(docs)
     if args.cmd == "corpus":
-        return kb_cmd_corpus(docs)
+        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)