opencode-skills-collection 4.0.41 → 4.0.43

package/bundled-skills/lore/scripts/find_duplicates.py

@@ -42,6 +42,8 @@ def get_entries():
         [sys.executable, str(script), "--json"],
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
     )
     if r.returncode != 0:
         print(r.stderr, file=sys.stderr)
@@ -128,6 +130,11 @@ def hash_suffix(eid: str):
 
 
 def main():
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except AttributeError:  # Python < 3.7
+        pass
+
     args = sys.argv[1:]
     threshold = 0.7
     json_output = "--json" in args
@@ -154,14 +161,17 @@ def main():
     # existing-vs-existing pairs (unchanged behavior)
     for i, a in enumerate(entries):
         for b in entries[i + 1:]:
-            if a["layer"] != b["layer"]:
-                continue
+            # Exact-hash matches are reported across layers (same text is
+            # a duplicate no matter which layer it landed in); fuzzy
+            # Jaccard comparisons stay within the same layer.
             if hash_suffix(a["id"]) == hash_suffix(b["id"]):
                 pairs.append((a, b, 1.0, "identical hash"))
                 continue
+            if a["layer"] != b["layer"]:
+                continue
             sim = jaccard(tokenize(a["text"]), tokenize(b["text"]))
             if sim >= threshold:
-                pairs.append((a, b, sim, f"similar text (≥{threshold})"))
+                pairs.append((a, b, sim, f"similar text (>= {threshold})"))
 
     # candidate-vs-existing pairs
     if candidates:
@@ -176,7 +186,7 @@ def main():
             )
             if sim >= threshold:
                 pairs.append((candidates[0], a, sim,
-                              f"candidate similar to existing (≥{threshold})"))
+                              f"candidate similar to existing (>= {threshold})"))
 
     pairs.sort(key=lambda x: -x[2])
 

package/bundled-skills/lore/scripts/find_stale.py

@@ -8,20 +8,23 @@ Usage:
 
 Reports two categories:
 
-  Stale        : entry has not been `#verified` within the threshold
-                 (or has no #verified at all, and was added > threshold
-                 days ago).
-  Pending arch : entry already carries a `#stale:` tag and is waiting
-                 to be moved into .lore/archive/.
+  Stale           : entry has not been `#verified` within the threshold
+                    (or has no #verified at all, and was added > threshold
+                    days ago).
+  Pending review  : entry is superseded (carries `#stale`, or carries
+                    `#superseded-by` which implies staleness). (The skill
+                    does not auto-archive; this category is a heads-up that
+                    the entry is no longer accurate and should be reviewed
+                    or left as historical record.)
 
 Output is plain text by default, JSON with --json.
 
 Used by:
     - `audit` workflow (read-only)
     - `compress` workflow (advisory)
-    - `lore mirror` (sanity check before regenerating)
 """
 import json
+import os
 import subprocess
 import sys
 from datetime import date, datetime, timedelta
@@ -34,6 +37,8 @@ def get_entries():
         [sys.executable, str(script), "--json"],
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
     )
     if r.returncode != 0:
         print(r.stderr.strip(), file=sys.stderr)
@@ -54,6 +59,11 @@ def parse_date(s: str):
 
 
 def main():
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except AttributeError:  # Python < 3.7
+        pass
+
     days = 90
     json_output = "--json" in sys.argv[1:]
 
@@ -66,12 +76,34 @@ def main():
 
     entries = get_entries()
     stale = []
-    pending_arch = []
+    pending_review = []
+
+    # Build a quick lookup for chain validation.
+    by_id = {e["id"]: e for e in entries}
+
+    broken_chains = []
+    pending_by_chain = {}  # replaced_by -> [entry, ...]
 
     for e in entries:
-        # Already marked stale → pending archive
-        if "stale" in e["tags"]:
-            pending_arch.append(e)
+        # Superseded (tagged #stale, or carrying #superseded-by which
+        # implies staleness per references/entry-format.md) -> pending
+        # review (and maybe broken chain)
+        if "stale" in e["tags"] or e.get("replaced_by"):
+            target = e.get("replaced_by")
+            if target and target not in by_id:
+                broken_chains.append({
+                    "id": e["id"],
+                    "file": e["file"],
+                    "text": e["text"],
+                    "missing_target": target,
+                })
+            if target:
+                pending_by_chain.setdefault(target, []).append(e)
+            else:
+                # No chain info — keep under a sentinel so the existing
+                # output still includes it.
+                pending_by_chain.setdefault(None, []).append(e)
+            pending_review.append(e)
             continue
 
         # Determine the entry's freshness date
@@ -90,7 +122,11 @@ def main():
             "threshold_days": days,
             "as_of": today.isoformat(),
             "stale": stale,
-            "pending_archive": pending_arch,
+            "pending_review": pending_review,
+            "chains": {target: [e["id"] for e in entries_]
+                       for target, entries_ in pending_by_chain.items()
+                       if target is not None},
+            "broken_chains": broken_chains,
         }
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -104,12 +140,28 @@ def main():
         print(f"    ref date: {ref}")
 
     print()
-    print("=== Pending archive (tagged #stale) ===")
-    if not pending_arch:
+    print("=== Pending review (tagged #stale, grouped by replacement) ===")
+    if not pending_by_chain:
         print("  (none)")
-    for e in pending_arch:
-        print(f"  [{e['file']}] {e['id']} {e['text']}")
-        print(f"    marked stale: {e['tags']['stale']}")
+    for target, entries_ in sorted(
+        pending_by_chain.items(), key=lambda kv: (kv[0] is None, kv[0] or "")
+    ):
+        if target is None:
+            print("  (no #superseded-by chain):")
+        else:
+            print(f"  -> superseded-by {target}:")
+        for e in entries_:
+            chain = (
+                f" -> {e['replaced_by']}" if e.get("replaced_by") else ""
+            )
+            print(f"    [{e['file']}] {e['id']} {e['text']}{chain}")
+
+    if broken_chains:
+        print()
+        print("=== Broken chains (#superseded-by target not found) ===")
+        for b in broken_chains:
+            print(f"  [{b['file']}] {b['id']} {b['text']}")
+            print(f"    missing: {b['missing_target']}")
 
 
 if __name__ == "__main__":

package/bundled-skills/lore/scripts/history.py

@@ -14,6 +14,7 @@ import re
 import subprocess
 import sys
 from pathlib import Path
+import os as _os
 import json as _json  # standard library; aliased to avoid clashing with future vars
 
 
@@ -21,6 +22,34 @@ import json as _json  # standard library; aliased to avoid clashing with future
 ENTRY_ID_RE = re.compile(r"^[A-Z]+-\d{4}-\d{2}-\d{2}-[a-f0-9]{4}$")
 
 
+# Date-only ISO pattern (YYYY-MM-DD). Used to detect inputs that need
+# normalization before being passed to `git log --since=` (see below).
+_DATE_ONLY_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def normalize_since(value):
+    """Normalize a `--since` value to a precise timestamp before git log.
+
+    `git log --since=YYYY-MM-DD` interpretation is version-dependent:
+    older git versions parse it as the user's local-timezone midnight,
+    newer versions as UTC midnight. A commit made early in the day in
+    any timezone can therefore be silently dropped when filtering by a
+    same-day `#added` tag.
+
+    Defense: when the input is date-only (no time component), append
+    `T00:00:00` so git's date parser treats it as a precise timestamp.
+    Strings that already contain a time component (T or space) are
+    passed through unchanged. None passes through unchanged.
+
+    Refs: https://git-scm.com/docs/git-log#_date_formats
+    """
+    if value is None or not isinstance(value, str):
+        return value
+    if not _DATE_ONLY_RE.match(value):
+        return value
+    return value + "T00:00:00"
+
+
 def parse_arg(arg: str):
     """Dispatch the first positional argument to entry / file / scope form.
 
@@ -257,6 +286,7 @@ def render_json(meta, commits):
         "code_file": meta["code_file"],
         "since": meta["since"],
         "since_source": meta["since_source"],
+        "chain": meta.get("chain"),
         "commits": commits,
     }
     return _json.dumps(payload, indent=2, ensure_ascii=False)
@@ -267,15 +297,32 @@ def render_markdown(meta, commits):
 
     Args:
         meta: dict with keys entry_id, lore_file, code_file, since,
-              since_source.
+              since_source, and optionally _chain_entries (raw entry dicts).
         commits: list of commit dicts (see parse_commit_line + extract_refs).
 
     Returns:
         Markdown string ready for stdout.
     """
     lines = []
-    lines.append(f"# history: [{meta['entry_id']}]")
+    title_suffix = ""
+    if meta.get("_chain_entries"):
+        title_suffix = " --follow-superseded"
+    lines.append(f"# history: [{meta['entry_id']}]{title_suffix}")
     lines.append("")
+
+    chain_entries = meta.get("_chain_entries")
+    if chain_entries:
+        lines.append("## Chain")
+        for idx, e in enumerate(chain_entries, start=1):
+            next_link = (
+                f"\n   -> superseded-by -> {e.get('replaced_by')}"
+                if e.get("replaced_by") else "\n   -> no successor"
+            )
+            lines.append(
+                f"{idx}. [{e['id']}] ({e['file']}) - {e['text']}{next_link}"
+            )
+        lines.append("")
+
     lines.append(f"> Entry: {meta['lore_file']}")
     since_suffix = " (entry #added date)" if meta.get("since_source") == "entry_added" else ""
     lines.append(f"> Since: {meta['since']}{since_suffix}")
@@ -401,24 +448,68 @@ def _enrich_commits_with_body_and_refs(project_root, commits):
             c["refs"] = extract_refs(msg)
 
 
+def walk_supersede_chain(entries_by_id, start_id, max_depth=20):
+    """Follow #superseded-by links forward from start_id.
+
+    Returns a list of entry dicts [start, successor1, successor2, ...].
+    Stops when an entry has no replaced_by tag, the target is missing,
+    or max_depth is reached (cycle protection).
+
+    `entries_by_id` is a dict {id: entry_dict} from list_entries.py --json.
+    """
+    chain = []
+    seen = set()
+    current_id = start_id
+    for _ in range(max_depth):
+        if current_id in seen:
+            break  # cycle; don't loop forever
+        seen.add(current_id)
+        entry = entries_by_id.get(current_id)
+        if entry is None:
+            break
+        chain.append(entry)
+        next_id = entry.get("replaced_by")
+        if not next_id:
+            break
+        current_id = next_id
+    return chain
+
+
 def main():
     args = sys.argv[1:]
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except AttributeError:  # Python < 3.7
+        pass
     json_mode = "--json" in args
+    follow_superseded = "--follow-superseded" in args
     since_override = None
     for a in args:
         if a.startswith("--since="):
             since_override = a.split("=", 1)[1]
 
-    positional = [a for a in args if a != "--json" and not a.startswith("--since=")]
+    positional = [
+        a for a in args
+        if a != "--json"
+        and a != "--follow-superseded"
+        and not a.startswith("--since=")
+    ]
     if not positional:
-        print("usage: lore history <entry-id|file-path|--scope=NAME>",
-              file=sys.stderr)
+        print(
+            "usage: lore history <entry-id|file-path|--scope=NAME> "
+            "[--follow-superseded] [--since=YYYY-MM-DD] [--json]",
+            file=sys.stderr,
+        )
         die(ERR_USAGE, "missing argument")
 
     parsed = parse_arg(positional[0])
     if parsed is None:
         die(ERR_USAGE, f"unrecognized argument: {positional[0]}")
 
+    if follow_superseded and parsed["form"] != "entry":
+        print("[WARN] --follow-superseded only applies to the entry form; ignored.",
+              file=sys.stderr)
+
     project_root = _find_lore_root_or_die()
 
     if not _is_git_repo(project_root):
@@ -428,33 +519,147 @@ def main():
 
     if parsed["form"] == "entry":
         entries = _load_entries_via_subprocess()
+        entries_by_id = {e["id"]: e for e in entries}
         entry = find_entry(entries, parsed["value"])
         if entry is None:
             ids = ", ".join(e["id"] for e in entries[:20])
             more = "" if len(entries) <= 20 else f" (and {len(entries)-20} more)"
             die(ERR_NO_ENTRY,
                 f"Entry {parsed['value']} not found. Available: {ids}{more}")
-        since = since_override or extract_added_date(entry.get("tags", {}))
-        if since is None:
-            print("warning: entry has no #added tag; using full history",
-                  file=sys.stderr)
-            since = "1970-01-01"
-        code_file = resolve_code_file(entry)
-        try:
-            commits = run_git_log(project_root, since, code_file)
-        except RuntimeError as exc:
-            die(ERR_GIT_FAIL, str(exc))
-        _enrich_commits_with_body_and_refs(project_root, commits)
-        meta = _build_meta_entry(entry, code_file, since, "entry_added")
-        out = render_json(meta, commits) if json_mode else render_markdown(meta, commits)
-        print(out)
+
+        chain = ([entry] if not follow_superseded
+                 else walk_supersede_chain(entries_by_id, entry["id"]))
+
+        if not follow_superseded:
+            since = since_override or extract_added_date(entry.get("tags", {}))
+            use_full_history = since is None
+            if since is None:
+                print("warning: entry has no #added tag; using full history",
+                      file=sys.stderr)
+                since = "1970-01-01"
+            since = normalize_since(since)
+            code_file = resolve_code_file(entry)
+            try:
+                commits = run_git_log(
+                    project_root,
+                    None if use_full_history else since,
+                    code_file,
+                )
+            except RuntimeError as exc:
+                die(ERR_GIT_FAIL, str(exc))
+            _enrich_commits_with_body_and_refs(project_root, commits)
+            since_source = "user_arg" if since_override else "entry_added"
+            meta = _build_meta_entry(entry, code_file, since, since_source)
+            meta["chain"] = None
+            meta["_chain_entries"] = None
+            out = render_json(meta, commits) if json_mode else render_markdown(meta, commits)
+            print(out)
+            return
+
+        # --follow-superseded: iterate over the entire chain and collect
+        # per-entry logs. Each successor may point at a different file/date.
+        per_entry = []
+        for idx, e in enumerate(chain):
+            if idx == 0 and since_override is not None:
+                e_since_raw = since_override
+                e_since_source = "user_arg"
+            else:
+                e_since_raw = extract_added_date(e.get("tags", {}))
+                use_full_history = e_since_raw is None
+                if e_since_raw is None:
+                    print(f"warning: entry {e['id']} has no #added tag; using full history",
+                          file=sys.stderr)
+                    e_since_raw = "1970-01-01"
+                e_since_source = "entry_added"
+            if idx == 0 and since_override is not None:
+                use_full_history = False
+            e_since = normalize_since(e_since_raw)
+            e_code_file = resolve_code_file(e)
+            try:
+                e_commits = run_git_log(
+                    project_root,
+                    None if use_full_history else e_since,
+                    e_code_file,
+                )
+            except RuntimeError as exc:
+                die(ERR_GIT_FAIL, str(exc))
+            _enrich_commits_with_body_and_refs(project_root, e_commits)
+            per_entry.append((e, e_since, e_code_file, e_since_source, e_commits))
+
+        if json_mode:
+            chain_meta = [
+                {
+                    "entry_id": e["id"],
+                    "lore_file": e["file"],
+                    "code_file": cf,
+                    "since": s,
+                }
+                for (e, s, cf, _, _) in per_entry
+            ]
+            results = [
+                {
+                    "entry_id": e["id"],
+                    "lore_file": e["file"],
+                    "code_file": cf,
+                    "since": s,
+                    "since_source": ss,
+                    "commits": commits,
+                }
+                for (e, s, cf, ss, commits) in per_entry
+            ]
+            # Top-level keeps first entry's fields for backward compat
+            first_e, first_since, first_cf, first_ss, first_commits = per_entry[0]
+            payload = {
+                "entry_id": first_e["id"],
+                "lore_file": first_e["file"],
+                "code_file": first_cf,
+                "since": first_since,
+                "since_source": first_ss,
+                "chain": chain_meta,
+                "commits": first_commits,
+                "results": results,
+            }
+            # Preserve _chain_entries style for any downstream that expects it
+            payload["_chain_entries"] = None
+            print(_json.dumps(payload, indent=2, ensure_ascii=False))
+            return
+
+        # Markdown: Chain section then per-entry blocks
+        out_lines = []
+        out_lines.append(f"# history: [{chain[0]['id']}] --follow-superseded")
+        out_lines.append("")
+        out_lines.append("## Chain")
+        for idx, (e, _, _, _, _) in enumerate(per_entry, start=1):
+            next_link = (
+                f"\n   -> superseded-by -> {e.get('replaced_by')}"
+                if e.get("replaced_by") else "\n   -> no successor"
+            )
+            out_lines.append(
+                f"{idx}. [{e['id']}] ({e['file']}) - {e['text']}{next_link}"
+            )
+        out_lines.append("")
+        for (e, e_since, e_code_file, e_since_source, e_commits) in per_entry:
+            meta = _build_meta_entry(e, e_code_file, e_since, e_since_source)
+            meta["_chain_entries"] = None
+            # Render each entry's block without re-adding the Chain header
+            block = render_markdown(meta, e_commits)
+            # render_markdown starts with "# history: [id]" — keep it, but
+            # the top already has the --follow-superseded title.
+            out_lines.append(block.rstrip())
+            out_lines.append("")
+        print("\n".join(out_lines).rstrip() + "\n")
         return
 
     if parsed["form"] == "file":
         since = since_override or "1970-01-01"
+        since = normalize_since(since)
         code_file = parsed["value"]
         try:
-            commits = run_git_log(project_root, since, code_file)
+            commits = run_git_log(
+                project_root,
+                since if since_override else None,
+                code_file,
+            )
         except RuntimeError as exc:
             die(ERR_GIT_FAIL, str(exc))
         _enrich_commits_with_body_and_refs(project_root, commits)
@@ -472,13 +677,20 @@ def main():
     if parsed["form"] == "scope":
         layer_files = _resolve_scope_to_md_files(project_root, parsed["value"])
         scope_payloads = []  # only used when json_mode is True
+        scope_since = normalize_since(since_override or "1970-01-01")
         for layer_name, md_path in layer_files:
             # For scope form we treat each .md file as a "code file" stand-in:
             # we git log the md file's project-relative path to find commits
             # that touched that lore file. (Useful for tracking lore edits.)
-            rel = str(md_path.relative_to(project_root))
+            rel = str(md_path.relative_to(project_root)).replace(
+                _os.sep, "/"
+            )
             try:
-                commits = run_git_log(project_root, "1970-01-01", rel)
+                commits = run_git_log(
+                    project_root,
+                    scope_since if since_override else None,
+                    rel,
+                )
             except RuntimeError as exc:
                 die(ERR_GIT_FAIL, str(exc))
             _enrich_commits_with_body_and_refs(project_root, commits)
@@ -487,7 +699,7 @@ def main():
                     "entry_id": f"<scope:{parsed['value']}/{layer_name}>",
                     "lore_file": rel,
                     "code_file": rel,
-                    "since": "1970-01-01",
+                    "since": scope_since,
                     "since_source": "scope_form",
                 }
                 scope_payloads.append({

package/bundled-skills/lore/scripts/id_hash.py

@@ -7,10 +7,13 @@ Usage:
 Output:
     The 4-char lowercase hex hash that goes into an entry's ID, e.g. `a3f2`.
 
-The hash is `sha256(text).hexdigest()[:4]`. This is the same algorithm
-described in `references/entry-format.md` (ID generation section), so
-running this script always produces the ID component a lore agent
-would assign.
+The hash is `sha256(text).hexdigest()[:4]`. This matches the algorithm
+in `references/entry-format.md` and what `list_entries.py` uses when
+re-reading an entry from disk (it strips `#tag:value` pairs before
+hashing). To stay consistent, **pass the entry body WITHOUT the inline
+tags** — i.e. the text that goes between the `[ID]` and the first `#`.
+Including tags in the input here will produce a different hash than the
+file's stored ID, breaking round-trip verification.
 
 Cross-platform: works on Windows / Linux / macOS with Python 3.6+.
 """