@jenga-ai/agent 3.6.0 → 4.1.0

package/scripts/audit-twin-divergence.sh

@@ -1,693 +0,0 @@
-#!/usr/bin/env bash
-# scripts/audit-twin-divergence.sh — report UNEXPECTED content divergence between
-# each skills/<name>/ source and its skills/j-<name>/ twin (E50_S19_T01).
-#
-# Why this exists
-# ---------------
-# Every skills/j-<name>/ twin differs from its skills/<name>/ source. Most of that
-# difference is produced deliberately by scripts/generate-j-alias.sh and is CORRECT.
-# Some of it is missing content — a fix that landed in a bare directory and never
-# reached its twin. That second class is invisible in this repo (a bare path still
-# resolves, because the bare directory is still here) but is fatal downstream:
-# .publicignore blocks the bare-name directories, so the public mirror ships ONLY the
-# twins. A gap in a twin is a gap for every consumer.
-#
-# Confirmed instance, and this script's primary fixture: E22_S09_T07 (commit f3daaa8)
-# added parse_stage_id_from_text() to skills/j-publish/scripts/npm_stage_pipeline.sh and
-# a CI-log capture block to skills/j-publish/adapters/npm-ci.md. Neither reached
-# skills/j-publish/. A public-mirror consumer reported it as "E22_S09_T07 has not been
-# addressed" while the board read Merged. Both were right.
-#
-# This script is READ-ONLY. It reports; it never writes. Back-fill is E50_S19_T02.
-#
-# Classification rules — derived from the generator, not from observed diffs
-# -------------------------------------------------------------------------
-# Every rule below is a port of what scripts/generate-j-alias.sh actually does, with
-# its source line references. Inferring the rules from observed diffs instead would
-# let a transform the generator performs be misread as a gap and — far worse — let a
-# genuine gap be waved through as "probably just a path rewrite."
-#
-#   Transform 1 (generate-j-alias.sh L180-182): full rmtree + copytree of
-#     skills/<name>/ into skills/j-<name>/.
-#     => Audited as a FILE-SET comparison. A file in the source with no counterpart in
-#        the twin is MISSING_FILE; the reverse is EXTRA_FILE. Both are unexpected.
-#
-#   Transform 2 (L176-177, L184-195): literal substring replace of "skills/<name>/"
-#     with "skills/j-<name>/" across every copied file. This is also what rewrites the
-#     .claude/skills/<name>/ and .agents/skills/<name>/ mirrored-install fallback
-#     paths — they fall out of the same replace.
-#     => Audited by reconstructing the expected twin file as
-#        source.replace("skills/<name>/", "skills/j-<name>/") and comparing. A
-#        mismatch is CONTENT_DRIFT. Note this is directional in both senses: a twin
-#        that still carries a bare "skills/<name>/" self-reference fails here too,
-#        which is the same defect class E50_S11 exists to remove.
-#
-#   Transform 3 (L262): frontmatter rewrite name: j.<name> -> name: j.j-<name>.
-#     => TOLERATED IN BOTH DIRECTIONS. The generator emits j.j-<name>, but E50_S10's
-#        settled contract keeps the canonical twin at j.<name>, and E50_S15 lands that
-#        rewrite. This audit must not force either value, so it accepts j.j-<name> or
-#        j.<name> and reports neither. Any OTHER name: value is unexpected.
-#
-#   Transform 4 (L264-308): description: reframed as a polyfill alias; keywords: gets
-#     j-<name> and polyfill appended (list created if absent); examples: gets a
-#     "j-<name>" entry appended if that list already exists; and a generated
-#     lockstep/duplicate-alias note inserted just below the body's first H1.
-#     => Reconstructed byte-for-byte and compared. A mismatch is SKILL_DRIFT.
-#
-# Anything a transform above does not explain is UNEXPECTED and is a candidate content
-# gap. That is the entire output of this script.
-#
-# Scope decisions
-# ---------------
-# Three bare-name directories have no twin and are skipped, reported as informational:
-#   - skills/index/                   — not a skill, has no SKILL.md; the generator
-#                                       hard-errors on it (L118-121).
-#   - skills/jenga/                   — hard-excluded from twin generation (L110-113,
-#   - skills/jenga-permission-level/     E50_S06_T01). A twin must never exist.
-# A j-<name> directory with no bare source is likewise skipped and reported: it is
-# already at its sole canonical name (e.g. skills/j-playbook/, renamed by E50_S13), so
-# there is no source to diverge from.
-#
-# The skills/init/ <-> skills/j-init/ pair IS AUDITED. This is a deliberate decision,
-# recorded here because the generator refuses that pair (L97-100) as hand-maintained
-# and predating it, so one could argue for skipping it outright. Skipping is the wrong
-# call: j-init's scripts/ tree is shipped to the public mirror exactly like every other
-# twin's, so it can carry exactly the content gap this script hunts, and excluding it
-# would create a blind spot precisely where nothing else is watching.
-#
-# Because the generator never runs on that pair, its SKILL.md's generator-authored
-# regions are hand-written by design and reconstruction is not the specification for
-# them. For a hand-maintained pair only, SKILL.md is compared as:
-#   - frontmatter: every field EXCEPT name/description/keywords/examples must match the
-#     source after transform 2 (this still catches, say, a frontmatter field added to
-#     the source and never mirrored);
-#   - body: compared from the first "## " heading onward, since the H1 and the
-#     alias note above it are hand-authored.
-# The preamble between H1 and the first "## " heading is therefore not compared — so
-# to stop that becoming a silent blind spot, the script asserts the SOURCE's preamble
-# is empty and reports PREAMBLE_UNCOMPARED if it ever stops being empty. Everything
-# outside SKILL.md in that pair is compared with no tolerance at all.
-#
-# Usage:
-#   scripts/audit-twin-divergence.sh [repo-root] [--diff]
-#
-#   repo-root  Root of the tree to audit. Defaults to $JENGA_PROJECT_DIR. Passing it
-#              explicitly is what lets E50_S19_T03 run this against a
-#              public-mirror-shaped tree (bare-name directories absent) rather than
-#              only against the private repo, where the surviving bare directories
-#              mask this whole defect class.
-#   --diff     Also print a unified diff for every unexpected divergence.
-#   --min-pairs <n>
-#              Fail unless at least <n> twinned pairs were actually audited.
-#              Default 0 (no constraint).
-#
-#              This exists because a clean exit here is otherwise fail-open in a
-#              specific and easily-missed way: a tree containing NO twinned pairs at
-#              all audits nothing, finds nothing, and reports success. E50_S19_T03 hit
-#              exactly that — run against a public-mirror-shaped tree, where the
-#              bare-name sources are stripped by .publicignore, this script audits 0
-#              pairs and exits 0. That is a true statement and a worthless one, and it
-#              would read as a green gate to anyone not checking the pair count. Pass
-#              --min-pairs to assert the audit examined the population you expected.
-#
-# Exit codes:
-#   0  no unexpected divergence — usable as a gate
-#   1  at least one unexpected divergence
-#   2  usage or environment error, including --min-pairs not being met
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-REPO_ROOT=""
-OPT_DIFF="0"
-OPT_MIN_PAIRS="0"
-
-usage() {
-  echo "Usage: $(basename "$0") [repo-root] [--diff] [--min-pairs <n>]" >&2
-  echo "  Reports unexpected divergence between skills/<name>/ and skills/j-<name>/." >&2
-  echo "  Exits 0 when none remain, 1 when any do, 2 on a usage/environment error." >&2
-}
-
-while [ "$#" -gt 0 ]; do
-  case "$1" in
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    --diff)
-      OPT_DIFF="1"
-      ;;
-    --min-pairs)
-      shift
-      if [ "$#" -eq 0 ]; then
-        echo "audit-twin-divergence.sh: error: --min-pairs requires a number" >&2
-        usage
-        exit 2
-      fi
-      case "$1" in
-        ''|*[!0-9]*)
-          echo "audit-twin-divergence.sh: error: --min-pairs expects a non-negative integer, got '$1'" >&2
-          exit 2
-          ;;
-      esac
-      OPT_MIN_PAIRS="$1"
-      ;;
-    -*)
-      echo "audit-twin-divergence.sh: error: unknown option '$1'" >&2
-      usage
-      exit 2
-      ;;
-    *)
-      if [ -n "$REPO_ROOT" ]; then
-        echo "audit-twin-divergence.sh: error: more than one repo-root given ('$REPO_ROOT', '$1')" >&2
-        usage
-        exit 2
-      fi
-      REPO_ROOT="$1"
-      ;;
-  esac
-  shift
-done
-
-if [ -z "$REPO_ROOT" ]; then
-  # Only fall back to the resolver when no explicit root was given, so this script
-  # stays runnable against a tree that is not a Jenga project checkout at all (the
-  # mirror-shaped-tree case in E50_S19_T03).
-  # SC1091 is disabled rather than left as an accepted info-level finding: this
-  # script's AC requires a clean default-level shellcheck run, and the sourced file
-  # does exist — shellcheck simply will not follow it without -x.
-  # shellcheck source=lib/resolve-project-dir.sh disable=SC1091
-  source "$SCRIPT_DIR/../lib/resolve-project-dir.sh"
-  REPO_ROOT="$JENGA_PROJECT_DIR"
-fi
-
-if [ ! -d "$REPO_ROOT" ]; then
-  echo "audit-twin-divergence.sh: error: repo root '$REPO_ROOT' is not a directory." >&2
-  exit 2
-fi
-
-if [ ! -d "$REPO_ROOT/skills" ]; then
-  echo "audit-twin-divergence.sh: error: '$REPO_ROOT' has no skills/ directory — not a tree this audit understands." >&2
-  exit 2
-fi
-
-export REPO_ROOT OPT_DIFF OPT_MIN_PAIRS
-
-# Implemented as a python heredoc for the same reason generate-j-alias.sh is: the
-# classification is a byte-exact port of that generator's frontmatter/body rewrite,
-# which is written in python. Keeping both in one language is what makes "traceable to
-# the generator" checkable by reading rather than by trusting a re-derivation in awk.
-python3 - <<'PY'
-import difflib
-import os
-import re
-import subprocess
-import sys
-
-repo_root = os.environ["REPO_ROOT"]
-want_diff = os.environ.get("OPT_DIFF") == "1"
-min_pairs = int(os.environ.get("OPT_MIN_PAIRS") or "0")
-skills_dir = os.path.join(repo_root, "skills")
-
-# Gitignored-artifact exclusion (E50_S19_T04, Defect 1)
-# --------------------------------------------------------------------------
-# A build artifact that is gitignored (e.g. skills/train/__pycache__/*.pyc,
-# .gitignore:11's `**/__pycache__`) exists only because someone ran the tooling
-# on a real working checkout, not because a fix landed in the source and never
-# reached the twin. Comparing it at all is the bug: it is present in the bare
-# source and absent from the twin purely as a byproduct of git never tracking
-# it in either place, and gets reported as a false-positive MISSING_FILE.
-#
-# This is driven from the repo's OWN ignore rules (`git check-ignore`) rather
-# than a hardcoded `__pycache__`/`*.pyc` literal. A bespoke list was rejected
-# deliberately: the next generated-artifact class (a new lint cache, a new
-# compiled-language build dir, anything else `.gitignore` or `.publicignore`
-# already knows about) would silently reintroduce this exact false positive,
-# and a literal list is something every contributor has to remember to update
-# by hand. Reusing `git check-ignore` means this script's exclusion rule stays
-# correct automatically as `.gitignore` evolves.
-#
-# Degrades sensibly on a non-git repo root: this script's own AC (T01) requires
-# it to work against an arbitrary repo root, including a public-mirror-shaped
-# tree assembled by rsync that may not be a git repository at all. When that is
-# the case there is no ignore-rule authority to consult, so the exclusion is
-# skipped entirely rather than erroring -- acceptable because a mirror-shaped
-# tree is built from an explicit --exclude-from list (.publicignore) that does
-# not carry gitignored build artifacts across in the first place.
-IS_GIT_REPO = False
-try:
-    _git_check = subprocess.run(
-        ["git", "-C", repo_root, "rev-parse", "--is-inside-work-tree"],
-        capture_output=True, text=True, timeout=10,
-    )
-    IS_GIT_REPO = _git_check.returncode == 0 and _git_check.stdout.strip() == "true"
-except (OSError, subprocess.SubprocessError):
-    IS_GIT_REPO = False
-
-
-def git_ignored_paths(paths):
-    """Returns the subset of the given absolute paths that git considers ignored.
-
-    Batches every path into a single `git check-ignore --stdin` call rather than
-    one subprocess per file. Exit code 1 (nothing matched) and 0 (something
-    matched) are both legitimate outcomes; anything else (128, a missing git
-    binary, a timeout) is treated as "cannot determine ignore status" and
-    degrades to reporting nothing ignored, matching the non-git-repo behavior
-    above rather than crashing the whole audit over an environment quirk.
-    """
-    if not IS_GIT_REPO or not paths:
-        return set()
-    try:
-        proc = subprocess.run(
-            ["git", "-C", repo_root, "check-ignore", "--stdin"],
-            input="\n".join(paths) + "\n",
-            capture_output=True, text=True, timeout=30,
-        )
-    except (OSError, subprocess.SubprocessError):
-        return set()
-    if proc.returncode not in (0, 1):
-        return set()
-    return {line for line in proc.stdout.splitlines() if line}
-
-# Pairs the generator refuses outright. See generate-j-alias.sh L110-113 (hard error,
-# E50_S06_T01) and L118-121 (no SKILL.md).
-NEVER_TWINNED = ("jenga", "jenga-permission-level", "index")
-
-# Pairs the generator refuses because they are hand-maintained and predate it
-# (generate-j-alias.sh L97-100). Audited anyway — see this file's Scope decisions.
-HAND_MAINTAINED = ("init",)
-
-key_re = re.compile(r"^([A-Za-z_][\w-]*):(.*)$")
-
-findings = []   # (pair, relpath, code, detail, expected_text, actual_text)
-notes = []      # informational, never affects exit status
-
-
-def record(pair, relpath, code, detail, expected=None, actual=None):
-    findings.append((pair, relpath, code, detail, expected, actual))
-
-
-def read_text(path):
-    """Returns (text, is_text). Binary/unreadable files fall back to byte compare."""
-    try:
-        with open(path, "r", encoding="utf-8") as fh:
-            return fh.read(), True
-    except (UnicodeDecodeError, OSError):
-        return None, False
-
-
-def read_bytes(path):
-    with open(path, "rb") as fh:
-        return fh.read()
-
-
-def walk_files(root):
-    rel_by_abs = {}
-    for dirpath, _dirnames, filenames in os.walk(root):
-        for fn in filenames:
-            abs_path = os.path.join(dirpath, fn)
-            rel_by_abs[abs_path] = os.path.relpath(abs_path, root)
-    ignored = git_ignored_paths(list(rel_by_abs.keys()))
-    if not ignored:
-        return set(rel_by_abs.values())
-    return {
-        rel for abs_path, rel in rel_by_abs.items()
-        if abs_path not in ignored
-    }
-
-
-def split_frontmatter(text, label):
-    """Returns (opening_line, fields, closing_line, body_lines).
-
-    Field parsing is the same informal line-oriented approach generate-j-alias.sh
-    L217-234 uses — deliberately, so the two agree on what a 'field' is.
-    """
-    lines = text.splitlines(keepends=True)
-    if not lines or lines[0].strip() != "---":
-        return None, None, None, None
-    close_idx = None
-    for idx in range(1, len(lines)):
-        if lines[idx].strip() == "---":
-            close_idx = idx
-            break
-    if close_idx is None:
-        return None, None, None, None
-
-    fields = []
-    i = 1
-    while i < close_idx:
-        line = lines[i]
-        m = key_re.match(line)
-        if not m:
-            i += 1
-            continue
-        block = [line]
-        j = i + 1
-        if m.group(2).strip() == "":
-            while j < close_idx and lines[j].startswith(" "):
-                block.append(lines[j])
-                j += 1
-        fields.append({"key": m.group(1), "lines": block})
-        i = j
-    return lines[0], fields, lines[close_idx], lines[close_idx + 1:]
-
-
-def find_field(fields, key):
-    for f in fields:
-        if f["key"] == key:
-            return f
-    return None
-
-
-def build_expected_skill_md(src_text, name):
-    """Byte-for-byte port of generate-j-alias.sh's transforms 2-4 on SKILL.md.
-
-    Mirrors L176-195 (path replace), L262 (name), L264-271 (description),
-    L273-286 (keywords/examples), L292-327 (note insertion + reassembly).
-    """
-    old_ref = "skills/%s/" % name
-    new_ref = "skills/j-%s/" % name
-
-    opening, fields, closing, body_lines = split_frontmatter(
-        src_text.replace(old_ref, new_ref), "source"
-    )
-    if fields is None:
-        return None
-
-    name_field = find_field(fields, "name")
-    desc_field = find_field(fields, "description")
-    if name_field is None or len(name_field["lines"]) != 1:
-        return None
-    if desc_field is None or len(desc_field["lines"]) != 1:
-        return None
-
-    # L262
-    name_field["lines"][0] = "name: j.j-%s\n" % name
-
-    # L264-271
-    original_desc = (
-        key_re.match(desc_field["lines"][0]).group(2).strip().strip("\"'").rstrip(".")
-    )
-    desc_field["lines"][0] = (
-        "description: Polyfill alias of the {n} skill under a collision-safe directory "
-        "name. Identical behavior to /{n} — {d}. Use when the bare /{n} form is "
-        "shadowed by another tool's own built-in command of the same name.\n"
-    ).format(n=name, d=original_desc)
-
-    # L273-286
-    keywords_field = find_field(fields, "keywords")
-    if keywords_field is not None:
-        keywords_field["lines"].append("  - j-%s\n" % name)
-        keywords_field["lines"].append("  - polyfill\n")
-    else:
-        fields.append({
-            "key": "keywords",
-            "lines": ["keywords:\n", "  - j-%s\n" % name, "  - polyfill\n"],
-        })
-    examples_field = find_field(fields, "examples")
-    if examples_field is not None:
-        examples_field["lines"].append('  - "j-%s"\n' % name)
-
-    new_frontmatter = []
-    for f in fields:
-        new_frontmatter.extend(f["lines"])
-
-    # L294-308
-    note_text = (
-        "This skill is a literal-directory-name duplicate of `skills/{n}/`. It exists "
-        "so that `/j-{n}` (and `j.j-{n}`) give a guaranteed-unshadowed way to reach "
-        "the same flow as `/{n}`, even if a host tool's own built-in command of the "
-        "same name would otherwise shadow or override the bare `/{n}` alias (Claude "
-        "Code's native skill resolution is a literal-string, directory-name-based "
-        "match — see `docs/skill-authoring.md`'s \"Invocation Convention\").\n\n"
-        "This file is generated/synced by `scripts/generate-j-alias.sh {n}` from "
-        "`skills/{n}/SKILL.md` — do not hand-edit it; re-run the generator instead to "
-        "pick up source changes."
-    ).format(n=name)
-    note_block = []
-    for para in note_text.split("\n\n"):
-        note_block.append(para + "\n")
-        note_block.append("\n")
-
-    heading_idx = None
-    for idx, bl in enumerate(body_lines):
-        if bl.startswith("# "):
-            heading_idx = idx
-            break
-    if heading_idx is not None:
-        insert_at = heading_idx + 1
-        if insert_at < len(body_lines) and body_lines[insert_at].strip() == "":
-            insert_at += 1
-        prefix = body_lines[:insert_at]
-        if prefix and prefix[-1].strip() != "":
-            prefix = prefix + ["\n"]
-        new_body = prefix + note_block + body_lines[insert_at:]
-    else:
-        new_body = note_block + body_lines
-
-    return "".join([opening] + new_frontmatter + [closing] + new_body)
-
-
-def normalize_name_line(text, name):
-    """Applies the transform-3 tolerance: j.j-<name> and j.<name> are both accepted.
-
-    Rewrites the twin's `name:` line to the generator's j.j-<name> form purely for the
-    purpose of comparison, and only when it holds one of the two accepted values. Any
-    third value is left alone so the diff surfaces it as unexpected.
-    """
-    accepted = ("j.j-%s" % name, "j.%s" % name)
-    out = []
-    seen = False
-    for line in text.splitlines(keepends=True):
-        if not seen:
-            m = key_re.match(line)
-            if m and m.group(1) == "name":
-                seen = True
-                value = m.group(2).strip().strip("\"'")
-                if value in accepted:
-                    out.append("name: j.j-%s\n" % name)
-                    continue
-        out.append(line)
-    return "".join(out)
-
-
-def body_from_first_h2(body_lines):
-    for idx, bl in enumerate(body_lines):
-        if bl.startswith("## "):
-            return "".join(body_lines[idx:])
-    return ""
-
-
-def preamble_between_h1_and_h2(body_lines):
-    """Body text between the first H1 and the first H2, exclusive of both."""
-    start = None
-    for idx, bl in enumerate(body_lines):
-        if bl.startswith("# "):
-            start = idx + 1
-            break
-    if start is None:
-        start = 0
-    end = len(body_lines)
-    for idx in range(start, len(body_lines)):
-        if body_lines[idx].startswith("## "):
-            end = idx
-            break
-    return "".join(body_lines[start:end]).strip()
-
-
-def audit_skill_md_hand_maintained(pair, src_text, twin_text):
-    """SKILL.md comparison for a pair the generator refuses (L97-100).
-
-    Compares every frontmatter field except the four transform-3/4 rewrites, and the
-    body from the first H2 onward. See this file's Scope decisions for why.
-    """
-    old_ref = "skills/%s/" % pair
-    new_ref = "skills/j-%s/" % pair
-    src_text = src_text.replace(old_ref, new_ref)
-
-    _o1, src_fields, _c1, src_body = split_frontmatter(src_text, "source")
-    _o2, twin_fields, _c2, twin_body = split_frontmatter(twin_text, "twin")
-    if src_fields is None or twin_fields is None:
-        record(pair, "SKILL.md", "FRONTMATTER_UNPARSEABLE",
-               "SKILL.md frontmatter could not be parsed on one or both sides")
-        return
-
-    generator_owned = ("name", "description", "keywords", "examples")
-    for f in src_fields:
-        if f["key"] in generator_owned:
-            continue
-        twin_f = find_field(twin_fields, f["key"])
-        if twin_f is None:
-            record(pair, "SKILL.md", "FRONTMATTER_FIELD_MISSING",
-                   "twin frontmatter has no '%s:' field, but the source does" % f["key"],
-                   "".join(f["lines"]), "")
-        elif "".join(twin_f["lines"]) != "".join(f["lines"]):
-            record(pair, "SKILL.md", "FRONTMATTER_FIELD_DRIFT",
-                   "twin frontmatter field '%s:' differs from the source" % f["key"],
-                   "".join(f["lines"]), "".join(twin_f["lines"]))
-
-    # The uncompared region must stay empty, or this tolerance becomes a blind spot.
-    src_preamble = preamble_between_h1_and_h2(src_body)
-    if src_preamble:
-        record(pair, "SKILL.md", "PREAMBLE_UNCOMPARED",
-               "source now has body text between its H1 and its first '## ' heading, "
-               "which this pair's hand-maintained tolerance does not compare — review "
-               "by hand and mirror it into the twin if it belongs there",
-               src_preamble, "")
-
-    src_rest = body_from_first_h2(src_body)
-    twin_rest = body_from_first_h2(twin_body)
-    if src_rest != twin_rest:
-        record(pair, "SKILL.md", "SKILL_DRIFT",
-               "twin body (from the first '## ' heading onward) differs from the source",
-               src_rest, twin_rest)
-
-
-def audit_pair(pair):
-    src_dir = os.path.join(skills_dir, pair)
-    twin_dir = os.path.join(skills_dir, "j-%s" % pair)
-    old_ref = "skills/%s/" % pair
-    new_ref = "skills/j-%s/" % pair
-
-    src_files = walk_files(src_dir)
-    twin_files = walk_files(twin_dir)
-
-    for rel in sorted(src_files - twin_files):
-        record(pair, rel, "MISSING_FILE",
-               "present in skills/%s/ but absent from the twin the mirror ships" % pair)
-    for rel in sorted(twin_files - src_files):
-        record(pair, rel, "EXTRA_FILE",
-               "present in the twin but absent from skills/%s/" % pair)
-
-    for rel in sorted(src_files & twin_files):
-        src_path = os.path.join(src_dir, rel)
-        twin_path = os.path.join(twin_dir, rel)
-
-        src_text, src_is_text = read_text(src_path)
-        twin_text, twin_is_text = read_text(twin_path)
-
-        if not (src_is_text and twin_is_text):
-            if read_bytes(src_path) != read_bytes(twin_path):
-                record(pair, rel, "BINARY_DRIFT",
-                       "binary (or non-UTF-8) file differs; the generator copies it verbatim")
-            continue
-
-        if rel == "SKILL.md":
-            if pair in HAND_MAINTAINED:
-                audit_skill_md_hand_maintained(pair, src_text, twin_text)
-                continue
-            expected = build_expected_skill_md(src_text, pair)
-            if expected is None:
-                record(pair, rel, "FRONTMATTER_UNPARSEABLE",
-                       "source SKILL.md frontmatter does not have the single-line "
-                       "name:/description: shape the generator requires (L247-250)")
-                continue
-            actual = normalize_name_line(twin_text, pair)
-            if expected != actual:
-                record(pair, rel, "SKILL_DRIFT",
-                       "twin SKILL.md differs from the source after the generator's "
-                       "transforms 2-4 are applied",
-                       expected, actual)
-            continue
-
-        expected = src_text.replace(old_ref, new_ref)
-        if expected != twin_text:
-            record(pair, rel, "CONTENT_DRIFT",
-                   "twin differs from skills/%s/%s after transform 2 (the "
-                   "skills/%s/ -> skills/j-%s/ path rewrite)" % (pair, rel, pair, pair),
-                   expected, twin_text)
-
-
-# ---- discover pairs -------------------------------------------------------------
-
-if not os.path.isdir(skills_dir):
-    sys.exit("audit-twin-divergence.sh: error: %s is not a directory" % skills_dir)
-
-entries = sorted(
-    d for d in os.listdir(skills_dir) if os.path.isdir(os.path.join(skills_dir, d))
-)
-bare_dirs = [d for d in entries if not d.startswith("j-")]
-twin_dirs = [d for d in entries if d.startswith("j-")]
-
-pairs = []
-for d in twin_dirs:
-    bare = d[2:]
-    if bare in bare_dirs:
-        pairs.append(bare)
-    else:
-        notes.append(
-            "skipped skills/%s/ — no skills/%s/ source; already at its sole canonical "
-            "name, so there is nothing to diverge from" % (d, bare)
-        )
-
-for d in bare_dirs:
-    if ("j-%s" % d) in twin_dirs:
-        continue
-    if d in NEVER_TWINNED:
-        notes.append(
-            "skipped skills/%s/ — hard-excluded from twin generation by the generator; "
-            "a twin must never exist for it" % d
-        )
-    else:
-        notes.append(
-            "skipped skills/%s/ — no skills/j-%s/ twin exists" % (d, d)
-        )
-
-for pair in pairs:
-    audit_pair(pair)
-
-# ---- report ---------------------------------------------------------------------
-
-for note in notes:
-    print("note: %s" % note)
-if notes:
-    print("")
-
-if findings:
-    current_pair = None
-    for pair, rel, code, detail, expected, actual in findings:
-        if pair != current_pair:
-            print("skills/j-%s/" % pair)
-            current_pair = pair
-        print("  %-26s %s" % (code, "skills/j-%s/%s" % (pair, rel)))
-        print("      %s" % detail)
-        if want_diff and expected is not None and actual is not None:
-            diff = difflib.unified_diff(
-                expected.splitlines(keepends=True),
-                actual.splitlines(keepends=True),
-                fromfile="expected (from skills/%s/%s)" % (pair, rel),
-                tofile="actual   (skills/j-%s/%s)" % (pair, rel),
-                n=2,
-            )
-            for line in diff:
-                sys.stdout.write("      | " + line if line.endswith("\n")
-                                 else "      | " + line + "\n")
-    print("")
-
-affected = sorted({f[0] for f in findings})
-print("audit-twin-divergence.sh: audited %d twinned pair(s) under %s"
-      % (len(pairs), skills_dir))
-
-# Checked before the findings verdict: "I audited fewer pairs than you expected" is a
-# statement about whether this run means anything at all, which has to be settled
-# before "and I found nothing wrong" is worth printing as a pass.
-if len(pairs) < min_pairs:
-    print("audit-twin-divergence.sh: error: only %d twinned pair(s) were audited, but "
-          "--min-pairs %d was required. A clean result over too small a population is "
-          "not a pass — check the tree actually contains the pairs you expected."
-          % (len(pairs), min_pairs))
-    sys.exit(2)
-
-if findings:
-    print("audit-twin-divergence.sh: %d unexpected divergence(s) across %d pair(s): %s"
-          % (len(findings), len(affected), ", ".join(affected)))
-    print("audit-twin-divergence.sh: each of the above is a candidate content gap — "
-          "back-fill it into the twin, or record it as an intentional twin-only "
-          "difference with a stated reason (E50_S19_T02).")
-    sys.exit(1)
-
-print("audit-twin-divergence.sh: no unexpected divergence — every difference between "
-      "each source and its twin is explained by the generator's transforms.")
-sys.exit(0)
-PY