@antoneeo/kb-agentic-skill 1.26.1 → 1.31.0

package/skills/kb-agentic-skill/scripts/docs_site.py

@@ -33,6 +33,7 @@ import re
 import shutil
 import subprocess
 import sys
+import zipfile
 import unicodedata
 import urllib.parse
 from datetime import datetime
@@ -767,6 +768,8 @@ def build_sources(docs, rows_of):
         name = mp.name[:-len(".meta.md")]
         t = _text(mp) or ""
         meta = sdlc_core.load_frontmatter(t.splitlines()) or {}
+        if knowledge.kb_is_tombstone(meta):
+            continue  # withdrawn: no bytes to show; corpus/INDEX.md keeps the row
         through = _v(meta, "extracted_through")
         parsed = knowledge.kb_parse_extracted_through(through) if through else None
         if not through:
@@ -947,6 +950,21 @@ def analysis_chain(body):
     return [{"step": s, "sections": found[s]} for s in CHAIN_STEPS]
 
 
+def companion_paths(stem):
+    """The documents named after a unit's stem: (key, docs-relative path). One list,
+    read by the chain page and by the work and feature lists."""
+    return (("merge", "solutions/MERGE_REVIEW_%s.md" % stem),
+            ("e2e", "solutions/E2E_TEST_%s.md" % stem),
+            ("request", "audit/requests/REQUEST_%s.md" % stem))
+
+
+def verify_links(docs, stem):
+    """The merge brief and E2E script of a unit, where they exist: who merges reads the
+    first while the work is open, who tests reads the second after it closed."""
+    return {key: path for key, path in companion_paths(stem)
+            if key in ("merge", "e2e") and (docs / path).is_file()}
+
+
 def link_companions(docs, pages):
     """Each analysis's merge brief, E2E script and request record, where they exist,
     and the project's North Star (R25)."""
@@ -962,11 +980,8 @@ def link_companions(docs, pages):
             continue
         stem = chain.pop("_stem")
         chain["north_star"] = north_star
-        chain["companions"] = {
-            key: path if path in pages else None
-            for key, path in (("merge", "solutions/MERGE_REVIEW_%s.md" % stem),
-                              ("e2e", "solutions/E2E_TEST_%s.md" % stem),
-                              ("request", "audit/requests/REQUEST_%s.md" % stem))}
+        chain["companions"] = {key: path if path in pages else None
+                               for key, path in companion_paths(stem)}
 
 
 def orientation_sources(docs):
@@ -1055,6 +1070,7 @@ def build_work(project, docs, facts):
         for key in ("status", "level", "since", "updated", "branch", "next"):
             if _v(meta, key):
                 card[key] = _v(meta, key)
+        card.update(verify_links(docs, p.stem[len("HANDOFF_"):]))
         cards.append(card)
     cards.sort(key=lambda c: c["name"].lower())
     cards.sort(key=lambda c: c.get("updated", ""), reverse=True)
@@ -1083,8 +1099,12 @@ def build_units(project, lens):
                 u[key] = _v(meta, field)
         if "id" not in u and _v(meta, "feature"):
             u["id"] = _v(meta, "feature")
+        u.update(verify_links(sdlc_core.ai_path(project), p.stem[len("ANALYSIS_"):]))
         units.append(u)
+    # newest first by declared start date (owner, 2026-10-19); undated last, by id
     units.sort(key=lambda u: (u.get("id", ""), u["path"]))
+    units.sort(key=lambda u: u.get("start", ""), reverse=True)
+    units.sort(key=lambda u: not u.get("start"))
     return units
 
 
@@ -1204,7 +1224,14 @@ def chronology(docs, pages):
         text = _text(p)
         # a shadow mirror is not an analysis to `validate` (list_analyses): not here either
         if text is not None and not sdlc_core.is_shadow(p, (text.splitlines() or [""])[0]):
+            # a Diary label ("closed", "Approved (R5)") names no unit: prefix the id, so
+            # the event reads on its own in the chronology (field case 2026-10-19)
+            uid = dict((k.lower(), v) for k, v in split_frontmatter(text)[0]).get("id", "").strip()
+            start = len(events)
             openers("solutions/" + p.name, "diary", sdlc_core.DIARY_SECTION)
+            if uid:
+                for e in events[start:]:
+                    e["label"] = "%s — %s" % (uid, e["label"])
     # spike outcomes: SPIKE_* in the code/kb/course lenses, RESEARCH_* in marketing
     for rel in sorted(["solutions/" + p.name for p in docs.glob("solutions/SPIKE_*.md")]
                       + ["spikes/" + p.name for p in docs.glob("spikes/RESEARCH_*.md")]):
@@ -1234,10 +1261,12 @@ def chronology(docs, pages):
             text = _text(p)
             if text is None:
                 continue
-            date = knowledge.frontmatter_date(
-                sdlc_core.load_frontmatter(text.splitlines()))
+            fm = sdlc_core.load_frontmatter(text.splitlines())
+            date = knowledge.frontmatter_date(fm)
             if not date:
                 continue
+            if kind == "source" and knowledge.kb_is_tombstone(fm):
+                continue
             if kind == "source":
                 name = p.name[:-len(suffix)]
                 add(date, kind, name, rel, source=name)
@@ -1272,6 +1301,29 @@ def check_out(out, docs):
     return out
 
 
+def check_zip(target, docs, out):
+    """Where `--zip` may write: a .zip file outside the docs root and outside the site."""
+    target = target.resolve()
+    if target.suffix.lower() != ".zip":
+        raise SiteError("--zip %s must name a .zip file." % target)
+    for folder, what in ((docs.resolve(), "the docs root"), (out.resolve(), "the site folder")):
+        if target == folder or folder in target.parents:
+            raise SiteError("--zip %s is inside %s %s." % (target, what, folder))
+    if target.exists() and not target.is_file():
+        raise SiteError("--zip %s exists and is not a file." % target)
+    return target
+
+
+def write_zip(out, target):
+    """The site as one file to share. Entry names always use '/': an archive whose names
+    carry '\\' (Windows PowerShell 5.1 Compress-Archive) unpacks on Linux and macOS as
+    files named `data\\core.js`, and the page then finds no data (field case 2026-10-19)."""
+    with zipfile.ZipFile(str(target), "w", zipfile.ZIP_DEFLATED) as z:
+        for p in sorted(out.rglob("*")):
+            if p.is_file() and p.name != MARKER:
+                z.write(str(p), p.relative_to(out).as_posix())
+
+
 def write_site(out, core, pages, kb):
     out.mkdir(parents=True, exist_ok=True)
     for rel in PAGE_FILES + ("data",):
@@ -1307,6 +1359,30 @@ def git_ignored(project, out):
         return None
 
 
+def ensure_ignored(project, out):
+    """Add the site folder to the project's .gitignore when git does not ignore it, so the
+    site's copy of the documents is not committed. An entry already in the file is never
+    rewritten (git may ignore it elsewhere, or the user negated it on purpose). Returns the
+    line added, or None; False when the folder stays not ignored."""
+    if git_ignored(project, out) is not False:
+        return None
+    rel = out.resolve().relative_to(project.resolve()).as_posix()
+    entry = rel + "/"
+    gi = project / ".gitignore"
+    try:
+        raw = gi.read_bytes() if gi.is_file() else b""
+        text = raw.decode("utf-8")
+        if {rel, entry, "/" + rel, "/" + entry} & {l.strip() for l in text.splitlines()}:
+            return False
+        nl = "\r\n" if "\r\n" in text else "\n"
+        sep = nl if text and not text.endswith(("\n", "\r")) else ""
+        with open(str(gi), "ab") as f:
+            f.write((sep + entry + nl).encode("utf-8"))
+    except (OSError, UnicodeDecodeError):
+        return False
+    return entry
+
+
 def _shown(path, docs):
     try:
         return Path(path).relative_to(docs).as_posix()
@@ -1322,11 +1398,14 @@ def main(argv=None):
     ap.add_argument("--docs-dir", dest="docs_dir", help="docs root name (ai_docs or mkt_docs)")
     ap.add_argument("--out", help="output folder (default: <project>/%s)" % DEFAULT_OUT)
     ap.add_argument("--open", action="store_true", help="open the site in the browser")
+    ap.add_argument("--zip", metavar="FILE",
+                    help="also write the site as one .zip to share; it opens on any system")
     args = ap.parse_args(argv)
     del _UNREADABLE[:]
     try:
         project, docs, name = resolve_root(args)
         out = check_out(Path(args.out) if args.out else project / DEFAULT_OUT, docs)
+        target = check_zip(Path(args.zip), docs, out) if args.zip else None
     except SiteError as exc:
         print("[ERROR] %s" % exc)
         return 2
@@ -1349,9 +1428,16 @@ def main(argv=None):
         ", %d topics, %d facts" % (len(kb["order"]), len(kb["facts"])) if kb else "", docs))
     for path, exc in _UNREADABLE:
         print("[ERROR] unreadable: %s (%s)" % (_shown(path, docs), exc))
-    if git_ignored(project, out) is False:
+    added = ensure_ignored(project, out)
+    if added:
+        print("[ok] added %s to %s so the site's copy of your documents is not committed."
+              % (added, project / ".gitignore"))
+    elif added is False:
         print("[note] %s is not git-ignored: add it to .gitignore so the site's copy of "
               "your documents is not committed." % out)
+    if target:
+        write_zip(out, target)
+        print("[ok] docs site zipped: %s (unzip it and open index.html)" % target)
     if args.open:
         import webbrowser
         webbrowser.open((out / "index.html").as_uri())