@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/generic-r0-leak-scan.sh

@@ -0,0 +1,282 @@
+#!/usr/bin/env bash
+# generic-r0-leak-scan.sh — deterministic PUBLIC fallback for the R0 leakage gate.
+#
+# When the maintainer's private ALIAS_AUDIT_CMD is unavailable (a normal local
+# machine), check-ccl-skills.sh runs this scan instead of leaving only an
+# "audit skipped" notice. It is a HIGH-SIGNAL, LOW-FALSE-POSITIVE public check —
+# NOT a replacement for the private alias audit.
+#
+# Scope: ONLY the ADDED lines of the current git diff (committed base..HEAD,
+# staged, unstaged, and untracked) restricted to shared-skill MARKDOWN surfaces
+# (skills/**/*.md, README.md, docs/**/*.md,
+# packages/opencode-plugin/commands/**/*.md,
+# .opencode/commands/**/*.md). Diff-scoping is deliberate: it never re-polices
+# pre-existing known debt, only what THIS change introduces. Markdown-only is
+# deliberate too: scripts and YAML overlays legitimately contain example tokens
+# and path-handling code, and the private alias audit (not this fallback) is the
+# comprehensive gate of record over every file type.
+#
+# Detected leak classes (each requires a CONCRETE shape, so prose and angle
+# placeholders like </Users> or <repo> do not trip it):
+#   - absolute local paths: /Users/<seg>, /home/<seg>, /private/var/<seg>, C:\<seg>
+#   - RFC1918 private IPv4 literals (10/8, 172.16-31/12, 192.168/16) — NOT loopback
+#   - internal-only hostnames: <label>.internal / .intranet / .corp
+#   - secret/token literals: key=<12+char quoted value>, or known vendor token prefixes
+#
+# Exit codes: clean=0 (prints generic_r0_leak_scan_ok), leak found=1 (prints the
+# offending lines), degraded=0 (prints generic_r0_leak_scan_degraded — a DISTINCT
+# status, NOT a reassuring _ok). Degraded fires when coverage is incomplete: not a
+# git work tree, OR no diff base resolves (no CCL_SKILL_BASE_REF / @{upstream} /
+# origin/main merge-base) while HEAD exists, so committed branch commits were NOT
+# scanned — the exact shallow / detached-HEAD CI case where a leak already committed
+# on the branch would otherwise pass as a silent _ok. Degraded is WARNING-PASS
+# (exit 0) by default because this is a best-effort preflight and the private
+# ALIAS_AUDIT_CMD is the gate of record; opt IN to a hard failure with
+# CCL_SKILL_R0_STRICT_BASE=1. A leak found in whatever WAS scanned still blocks
+# (exit 1) regardless of degraded. `--self-test` validates the matcher and the
+# clean/degraded status decision against in-memory fixtures (no git) and exits 0/1.
+set -euo pipefail
+
+# High-signal leak patterns (rg / Rust-regex syntax). A match anywhere on an
+# added line flags it. Kept narrow to hold false positives down.
+leak_patterns=(
+  '/Users/[A-Za-z0-9._-]'
+  '/home/[A-Za-z0-9._-]'
+  '/private/var/[A-Za-z0-9._-]'
+  '[A-Za-z]:\\[A-Za-z0-9._-]'
+  '(?:^|[^0-9.])10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}(?:[^0-9]|$)'
+  '(?:^|[^0-9.])192\.168\.[0-9]{1,3}\.[0-9]{1,3}(?:[^0-9]|$)'
+  '(?:^|[^0-9.])172\.(?:1[6-9]|2[0-9]|3[01])\.[0-9]{1,3}\.[0-9]{1,3}(?:[^0-9]|$)'
+  '[A-Za-z0-9][A-Za-z0-9-]*\.(?:internal|intranet|corp)(?:[^A-Za-z0-9]|$)'
+  '(?:^|[^A-Za-z0-9])AKIA[0-9A-Z]{16}(?:[^0-9A-Z]|$)'
+  '(?:^|[^A-Za-z0-9])gh[opsu]_[A-Za-z0-9]{36}'
+  '(?:^|[^A-Za-z0-9])glpat-[A-Za-z0-9_-]{20}'
+  '(?:^|[^A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{10,}'
+  '(?:^|[^A-Za-z0-9])sk-[A-Za-z0-9]{20,}'
+  '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+)
+# Secret-assignment pattern carries both quote chars, so build it with double
+# quotes (\" -> "), keeping rg escapes (\\s -> \s) intact.
+leak_patterns+=( "(?i:api[_-]?key|secret(?:[_-]?key)?|access[_-]?key|client[_-]?secret|password|passwd|token|bearer)[\"']?\\s*[:=]\\s*[\"'][A-Za-z0-9_+/.=-]{12,}[\"']" )
+
+# scan_stream: reads "path:lineno:content" lines on stdin, prints offenders on
+# stdout. Returns 0 normally (offenders may be empty), 2 on rg error.
+scan_stream() {
+  local args=() p out rc=0
+  for p in "${leak_patterns[@]}"; do args+=( -e "$p" ); done
+  # Capture rg's real status in the else branch (a false `if` with no else would
+  # otherwise reset $? to 0). rg: 0=match, 1=no match, 2=error.
+  if out="$(rg --no-line-number --no-filename --color never "${args[@]}" 2>/dev/null)"; then
+    rc=0
+  else
+    rc=$?
+  fi
+  if [ "$rc" -eq 0 ]; then
+    printf '%s\n' "$out"
+    return 0
+  fi
+  [ "$rc" -eq 1 ] && return 0   # no matches
+  echo "generic_r0_leak_scan_error: rg exited $rc" >&2
+  return 2
+}
+
+# emit_clean_result <degraded> <line_count> <file_count>
+# Prints the clean-outcome status line and returns its exit code. Isolated from
+# git so --self-test can exercise it. degraded=1 -> a DISTINCT scan_degraded
+# status (base unavailable; committed branch commits NOT covered), WARNING-PASS
+# (exit 0) by default, or BLOCK (exit 1) under CCL_SKILL_R0_STRICT_BASE=1.
+emit_clean_result() {
+  local degraded="$1" line_count="$2" file_count="$3"
+  if [ "$degraded" = 1 ]; then
+    echo "generic_r0_leak_scan_degraded: base unavailable (no CCL_SKILL_BASE_REF / @{upstream} / origin/main merge-base); committed branch commits NOT scanned — only worktree/staged/untracked. Best-effort preflight; degraded-clean is NOT proof, the private ALIAS_AUDIT_CMD is the gate of record. Set CCL_SKILL_BASE_REF for full coverage." >&2
+    if [ "${CCL_SKILL_R0_STRICT_BASE:-0}" = 1 ]; then
+      echo "generic_r0_leak_scan_degraded_blocking: CCL_SKILL_R0_STRICT_BASE=1 -> treating degraded coverage as a failure" >&2
+      return 1
+    fi
+    return 0
+  fi
+  echo "generic_r0_leak_scan_ok: scanned ${line_count} added markdown line(s) across ${file_count} file(s); no high-signal public leak patterns"
+  return 0
+}
+
+run_self_test() {
+  # Fixtures: "<expect>\t<content>" where expect is flag|clean.
+  local fixture_label='api_key'
+  local fixture_value='abcdef0123456789xyz'
+  local fixtures=(
+    $'flag\t/Users/alice/secret/path here'
+    $'flag\tconfig at /home/bob/.config/app'
+    $'flag\t/private/var/folders/ab/private-thing'
+    $'flag\twindows path C:\\Users\\admin\\file.txt'
+    $'flag\tconnect to 10.'$'1.2.3 today'
+    $'flag\tinternal host 192.'$'168.0.5 only'
+    $'flag\treach 172.'$'20.1.1 over vpn'
+    $'flag\tservice db.'$'internal is up'
+    $'flag\tAWS key AKIA'$'ABCDEFGHIJKLMNOP rotated'
+    $'flag\tgithub ghp_'$'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 leaked'
+    "flag"$'\t'"$fixture_label = \"$fixture_value\" set"
+    $'flag\tpassword: "hunter2hunter2hunter2"'
+    $'flag\tbegin block -----BEGIN RSA PRIVATE KEY-----'
+    $'clean\tsee <repo>/skills/foo for details'
+    $'clean\tpath under /home/<user>/config'
+    $'clean\tlocalhost 127.0.0.1 loopback only'
+    $'clean\trelease version 1.2.3.4beta notes'
+    $'clean\tset your api token in the settings page'
+    $'clean\tthe secret sauce of good design'
+    $'clean\tRFC1918 ranges like 10.x and 192.168.x'
+    $'clean\tuse base64 to encode the payload'
+    $'clean\ttask-runner sk module loaded'
+    $'clean\texample.invalid is a reserved test host'
+    $'clean\tSHA-256 digest of the file'
+  )
+  local failed=0 expect content line flagged
+  local i=1
+  for fx in "${fixtures[@]}"; do
+    expect="${fx%%$'\t'*}"
+    content="${fx#*$'\t'}"
+    line="selftest:${i}:${content}"
+    if [ -n "$(printf '%s\n' "$line" | scan_stream)" ]; then
+      flagged=flag
+    else
+      flagged=clean
+    fi
+    if [ "$flagged" != "$expect" ]; then
+      echo "generic_r0_leak_scan_self_test: MISMATCH expected=$expect got=$flagged :: $content" >&2
+      failed=1
+    fi
+    i=$((i + 1))
+  done
+  # Status-decision unit: base-unavailable clean outcome must be a DISTINCT
+  # scan_degraded (not a reassuring _ok), warning-pass by default, blocking under
+  # strict; a covered clean outcome must be scan_ok.
+  local dtext drc
+  dtext="$(emit_clean_result 1 0 0 2>&1)" && drc=0 || drc=$?
+  if ! printf '%s' "$dtext" | grep -q 'generic_r0_leak_scan_degraded'; then
+    echo "generic_r0_leak_scan_self_test: emit_clean_result(degraded) must print scan_degraded" >&2; failed=1
+  fi
+  if [ "$drc" -ne 0 ]; then
+    echo "generic_r0_leak_scan_self_test: degraded must be WARNING-PASS (exit 0) by default" >&2; failed=1
+  fi
+  dtext="$(CCL_SKILL_R0_STRICT_BASE=1 emit_clean_result 1 0 0 2>&1)" && drc=0 || drc=$?
+  if [ "$drc" -eq 0 ]; then
+    echo "generic_r0_leak_scan_self_test: CCL_SKILL_R0_STRICT_BASE=1 must make degraded BLOCK" >&2; failed=1
+  fi
+  if ! printf '%s' "$(emit_clean_result 0 5 2 2>&1)" | grep -q 'generic_r0_leak_scan_ok'; then
+    echo "generic_r0_leak_scan_self_test: emit_clean_result(covered) must print scan_ok" >&2; failed=1
+  fi
+
+  if [ "$failed" -ne 0 ]; then
+    echo "generic_r0_leak_scan_self_test_failed" >&2
+    return 1
+  fi
+  echo "generic_r0_leak_scan_self_test_ok"
+  return 0
+}
+
+# parse_diff: stdin = `git diff --unified=0` output; stdout = added markdown
+# lines as "relpath:newlineno:content". Tracks the +++ target file and the new
+# line counter from each @@ hunk header.
+parse_diff() {
+  awk '
+    /^diff --git / { file=""; next }
+    /^\+\+\+ / {
+      f=$0; sub(/^\+\+\+ /,"",f)
+      if (f=="/dev/null") { file=""; next }
+      sub(/^b\//,"",f)
+      file=f
+      next
+    }
+    /^@@ / {
+      if (match($0, /\+[0-9]+/)) { curline=substr($0, RSTART+1, RLENGTH-1)+0 }
+      next
+    }
+    /^\+/ {
+      if (file=="") next
+      if (file !~ /\.md$/) next
+      print file ":" curline ":" substr($0,2)
+      curline++
+      next
+    }
+  '
+}
+
+main_scan() {
+  local root="${1:-.}"
+  cd "$root"
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "generic_r0_leak_scan_degraded: not a git work tree at '$root'; cannot diff added lines (non-blocking)"
+    return 0
+  fi
+
+  local surfaces=( skills README.md docs packages/opencode-plugin/commands .opencode/commands )
+
+  # Resolve diff base (mirrors check-ccl-skills.sh): explicit override, then
+  # @{upstream}, then origin/main. merge_base may be empty when no base resolves
+  # (shallow / detached-HEAD CI, no origin). The staged/unstaged/untracked scans
+  # still run, but committed branch commits are then NOT covered — so when a HEAD
+  # exists yet no base resolved, mark the clean outcome degraded rather than let a
+  # branch-committed leak pass as a silent _ok.
+  local base merge_base degraded=0
+  base="${CCL_SKILL_BASE_REF:-}"
+  if [ -z "$base" ]; then
+    base="$(git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)"
+    [ -z "$base" ] && base="origin/main"
+  fi
+  merge_base="$(git merge-base "$base" HEAD 2>/dev/null || true)"
+  if [ -z "$merge_base" ] && git rev-parse --verify -q HEAD >/dev/null 2>&1; then
+    degraded=1
+  fi
+
+  local stream=""
+  if [ -n "$merge_base" ]; then
+    stream+="$(git diff --unified=0 "$merge_base" HEAD -- "${surfaces[@]}" 2>/dev/null | parse_diff)"$'\n'
+  fi
+  stream+="$(git diff --unified=0 --cached -- "${surfaces[@]}" 2>/dev/null | parse_diff)"$'\n'
+  stream+="$(git diff --unified=0 -- "${surfaces[@]}" 2>/dev/null | parse_diff)"$'\n'
+
+  # Untracked markdown files: every line counts as added.
+  local f rel
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in *.md) ;; *) continue ;; esac
+    rel="$f"
+    stream+="$(awk -v p="$rel" '{print p":"FNR":"$0}' "$f" 2>/dev/null)"$'\n'
+  done < <(git ls-files --others --exclude-standard -- "${surfaces[@]}" 2>/dev/null || true)
+
+  # Drop empty lines produced by the joins.
+  stream="$(printf '%s\n' "$stream" | sed '/^$/d')"
+
+  local file_count line_count offenders
+  line_count="$(printf '%s' "$stream" | grep -c . || true)"
+  file_count="$(printf '%s\n' "$stream" | sed -n 's/^\([^:]*\):.*/\1/p' | sort -u | grep -c . || true)"
+
+  if [ -z "$stream" ]; then
+    # No added lines in the worktree/staged/untracked scan. If the committed base
+    # was not covered this is under-scanned, not proven clean -> degraded.
+    if [ "$degraded" = 1 ]; then
+      if emit_clean_result 1 0 0; then return 0; else return $?; fi
+    fi
+    echo "generic_r0_leak_scan_ok: 0 added markdown line(s) in scope; nothing to scan"
+    return 0
+  fi
+
+  offenders="$(printf '%s\n' "$stream" | scan_stream)" || return 2
+  if [ -n "$offenders" ]; then
+    # A leak in whatever WAS scanned always blocks, degraded or not.
+    echo "generic_r0_leak_scan: high-signal public leak pattern(s) in added markdown lines:" >&2
+    printf '%s\n' "$offenders" | sed 's/^/  /' >&2
+    echo "generic_r0_leak_scan_failed: sanitize the line(s) above (use angle placeholders / generic terms), or run the private ALIAS_AUDIT_CMD audit if this is a false positive" >&2
+    return 1
+  fi
+  if emit_clean_result "$degraded" "$line_count" "$file_count"; then return 0; else return $?; fi
+}
+
+if ! command -v rg >/dev/null 2>&1; then
+  echo "generic_r0_leak_scan_error: missing required command: rg" >&2
+  exit 2
+fi
+
+case "${1:-}" in
+  --self-test) run_self_test ;;
+  *) main_scan "${1:-.}" ;;
+esac

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/governing-chain-diff.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""Executable spec for the row-set predicate in references/rule-consolidation.md.
+
+The obligation-preservation table's row set is defined there as: every obligation
+whose GOVERNING CHAIN differs before vs after, plus every obligation whose own
+text left a rewritten line. That predicate is prose an agent applies by hand, so
+this file computes it mechanically over two revisions of a markdown file and
+prints the derived row set — making the rule reproducible instead of asserted,
+and giving the challenge's "independently recompute the row set" obligation a
+tool it can actually run.
+
+The governing chain of an obligation is the ordered stack of normative ancestors
+it hangs under: the enclosing headings (outermost first) then any enclosing list
+items, each taken by NORMATIVE CONTENT rather than by label or position — so a
+parent that keeps its wording but moves does not count as changed, while one that
+keeps its position and rewrites its condition does.
+
+Usage:
+    governing-chain-diff.py BEFORE_FILE AFTER_FILE
+    governing-chain-diff.py --rev BEFORE_REV AFTER_REV PATH [--repo DIR]
+
+Exit status:
+    0  the derived row set is empty (no obligation changed chain or left a line)
+    1  the derived row set is non-empty (those obligations owe table rows)
+    2  usage or input error
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+
+# A heading line: capture level and text.
+_HEADING = re.compile(r"^(#{1,6})\s+(.*\S)\s*$")
+# A list item: capture indent width, and the text after the bullet/number marker.
+_LIST_ITEM = re.compile(r"^(\s*)(?:[-*+]|\d+[.)])\s+(.*\S)\s*$")
+# A markdown table row (leading pipe); these are data rows, not prose obligations.
+_TABLE_ROW = re.compile(r"^\s*\|")
+# A fenced code block delimiter.
+_FENCE = re.compile(r"^\s*(?:```|~~~)")
+
+
+def normalize(text: str) -> str:
+    """Collapse whitespace so cosmetic rewrapping is not read as a change."""
+    return " ".join(text.split())
+
+
+def content_key(text: str, *, chars: int = 120) -> str:
+    """Identity of an ancestor BY NORMATIVE CONTENT, not by label or position.
+
+    A bounded prefix is used so that appending a clause to a parent counts as the
+    same host while rewriting its opening condition does not. The bound is part
+    of the spec: `test_governing_chain_diff.sh` pins both directions.
+    """
+    return normalize(text)[:chars]
+
+
+@dataclass(frozen=True)
+class Obligation:
+    text: str
+    chain: tuple[str, ...]
+
+    @property
+    def key(self) -> str:
+        return normalize(self.text)
+
+
+# Sentence boundary: an ASCII terminator followed by whitespace, OR a CJK
+# terminator (。；：！？) with no whitespace requirement — CJK sentences abut
+# directly. Deliberately simple — it only has to split dense prose into
+# clause-sized units, and both revisions are split the same way, so a boundary
+# this misplaces still compares equal. Without the CJK arm, a dense CJK bullet
+# is one unsplittable block and a qualifier migrating between its sentences is
+# invisible — the exact failure this tool exists to catch. Known limitation:
+# ，、 are NOT split points (they are the dominant CJK clause separator and
+# splitting there would multiply micro-obligations into noise); a qualifier
+# moving between comma-joined clauses still surfaces, but as coarser
+# left-a-rewritten-line / governing-chain-changed rows on the enclosing block.
+_SENTENCE = re.compile(r"(?<=[.;:!?])\s+|(?<=[。；：！？])")
+
+# CJK ideograph/kana chars count double toward the obligation-length floor:
+# normalize() counts characters, and 25 ASCII chars is a short clause while 25
+# CJK chars is a full multi-clause rule, so an unweighted floor silently drops
+# short CJK gates (e.g. an 18-char blast-radius question) from the derived row
+# set. The floor itself scales down for ideograph-bearing text (min_chars*2//3,
+# default 25 → 16 effective chars ≈ 8 CJK chars) because CJK packs a complete
+# gate into far fewer characters; English text is unaffected (zero ideographs →
+# effective length == len, floor min_chars unchanged). Punctuation ranges
+# (U+3000-303F, U+FF00-FFEF) are deliberately EXCLUDED: one fullwidth mark in
+# an otherwise-English block must not flip the floor or inflate the length.
+# The sentence splitter above still treats 。；：！？ as terminators — that is
+# about boundary placement, not about length weighting.
+_CJK = re.compile(r"[぀-ヿ㐀-䶿一-鿿豈-﫿𠀀-𪛟]")
+
+
+def effective_len(text: str) -> int:
+    return len(text) + len(_CJK.findall(text))
+
+
+def length_floor(text: str, min_chars: int) -> int:
+    # Scaled, not hardcoded: a flat 16 would make the min_chars knob inert on
+    # CJK text (raising it filters nothing) and would RAISE the floor when a
+    # caller lowers it below 16 to catch shorter gates — a silent row-set loss
+    # on the merge-blocking deriver. 2//3 tracks the CJK density ratio.
+    return (min_chars * 2 // 3) if _CJK.search(text) else min_chars
+
+
+def split_obligations(block: str, chain: tuple[str, ...], min_chars: int) -> list[Obligation]:
+    """Decompose one item/paragraph into sentence-level obligations.
+
+    Granularity matters: in a dense entrypoint a single bullet can be thousands of
+    bytes and carry several distinct gates, and the failure this whole rule exists
+    for — a qualifier drifting from the rule it modified onto the neighbouring one
+    — happens BETWEEN sentences of two such bullets. A line-granular walk sees only
+    "both bullets changed" and never surfaces the clause that moved.
+
+    The block's FIRST sentence is what gives the block its normative identity, so
+    it carries the enclosing chain unchanged and becomes the immediate host of
+    every later sentence in the same block.
+    """
+    parts = [p.strip() for p in _SENTENCE.split(block) if effective_len(normalize(p)) >= length_floor(normalize(p), min_chars)]
+    if not parts:
+        return []
+    out = [Obligation(text=parts[0], chain=chain)]
+    host = chain + (content_key(parts[0]),)
+    out.extend(Obligation(text=p, chain=host) for p in parts[1:])
+    return out
+
+
+def parse(source: str, *, min_chars: int = 25) -> list[Obligation]:
+    """Extract obligations with their governing chains.
+
+    An obligation is a list item or a standalone prose paragraph long enough to
+    carry a gate (`min_chars` after normalization). Table rows and fenced code are
+    skipped: they are data, not obligations that can be re-parented.
+    """
+    obligations: list[Obligation] = []
+    headings: list[tuple[int, str]] = []  # (level, content_key)
+    list_stack: list[tuple[int, str]] = []  # (indent, content_key)
+    paragraph: list[str] = []
+    in_fence = False
+    # A list item may wrap across several lines. Its continuation lines belong to
+    # the item, not to a following paragraph — folding them in is what makes a
+    # cosmetic rewrap compare equal instead of reading as a rewritten line.
+    pending_item: list[str] | None = None
+    pending_indent = 0
+
+    def chain_now() -> tuple[str, ...]:
+        return tuple([key for _, key in headings] + [key for _, key in list_stack])
+
+    def flush_item() -> None:
+        nonlocal pending_item
+        if pending_item is None:
+            return
+        text = " ".join(pending_item)
+        obligations.extend(split_obligations(text, chain_now(), min_chars))
+        list_stack.append((pending_indent, content_key(text)))
+        pending_item = None
+
+    def flush_paragraph() -> None:
+        if not paragraph:
+            return
+        text = " ".join(paragraph)
+        obligations.extend(split_obligations(text, chain_now(), min_chars))
+        paragraph.clear()
+
+    for raw in source.split("\n"):
+        if _FENCE.match(raw):
+            flush_item()
+            flush_paragraph()
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+
+        if not raw.strip():
+            flush_item()
+            flush_paragraph()
+            # A blank line ends a paragraph but not the enclosing list context;
+            # markdown allows loose lists, so the stack is popped by indentation.
+            continue
+
+        if _TABLE_ROW.match(raw):
+            flush_item()
+            flush_paragraph()
+            continue
+
+        heading = _HEADING.match(raw)
+        if heading:
+            flush_item()
+            flush_paragraph()
+            level = len(heading.group(1))
+            while headings and headings[-1][0] >= level:
+                headings.pop()
+            headings.append((level, content_key(heading.group(2))))
+            list_stack.clear()
+            continue
+
+        item = _LIST_ITEM.match(raw)
+        if item:
+            flush_item()
+            flush_paragraph()
+            indent = len(item.group(1).expandtabs(4))
+            while list_stack and list_stack[-1][0] >= indent:
+                list_stack.pop()
+            pending_item = [item.group(2)]
+            pending_indent = indent
+            continue
+
+        # An indented non-item line directly under an open item continues it.
+        if pending_item is not None and (
+            len(raw) - len(raw.lstrip())
+        ) > pending_indent:
+            pending_item.append(raw.strip())
+            continue
+
+        flush_item()
+        # An UNINDENTED paragraph closes the list: in markdown it is a sibling of
+        # the list, not a child of its last item. Without this the paragraph would
+        # inherit whichever item happened to come last, so editing that item would
+        # report every following paragraph as re-parented — a false positive that
+        # is worse than a miss here, because it buries the real rows in noise.
+        if not raw[: len(raw) - len(raw.lstrip())]:
+            list_stack.clear()
+        paragraph.append(raw.strip())
+
+    flush_item()
+    flush_paragraph()
+    return obligations
+
+
+@dataclass(frozen=True)
+class Row:
+    reason: str  # "left-a-rewritten-line" | "governing-chain-changed"
+    text: str
+    before_chain: tuple[str, ...] = ()
+    after_chain: tuple[str, ...] = ()
+
+
+def derive_row_set(before: str, after: str) -> list[Row]:
+    """Apply the row-set predicate: chain changed, or own text left a line."""
+    before_obligations = parse(before)
+    after_obligations = parse(after)
+    after_by_key: dict[str, list[Obligation]] = {}
+    for obligation in after_obligations:
+        after_by_key.setdefault(obligation.key, []).append(obligation)
+
+    rows: list[Row] = []
+    for obligation in before_obligations:
+        survivors = after_by_key.get(obligation.key)
+        if not survivors:
+            rows.append(Row(reason="left-a-rewritten-line", text=obligation.text))
+            continue
+        # Survives verbatim: it owes a row only if its governing chain moved.
+        # Compare against the closest surviving chain so a duplicated obligation
+        # is not reported as re-parented merely because a copy sits elsewhere.
+        if any(s.chain == obligation.chain for s in survivors):
+            continue
+        rows.append(
+            Row(
+                reason="governing-chain-changed",
+                text=obligation.text,
+                before_chain=obligation.chain,
+                after_chain=survivors[0].chain,
+            )
+        )
+    return rows
+
+
+def read_rev(repo: str, rev: str, path: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", repo, "show", f"{rev}:{path}"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        print(f"error: cannot read {rev}:{path}", file=sys.stderr)
+        raise SystemExit(2)
+    return result.stdout
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=True, description=__doc__)
+    parser.add_argument("--rev", nargs=3, metavar=("BEFORE_REV", "AFTER_REV", "PATH"))
+    parser.add_argument("--repo", default=".")
+    parser.add_argument("files", nargs="*", metavar="BEFORE_FILE AFTER_FILE")
+    args = parser.parse_args(argv)
+
+    if args.rev:
+        before_rev, after_rev, path = args.rev
+        before = read_rev(args.repo, before_rev, path)
+        after = read_rev(args.repo, after_rev, path)
+        label = path
+    elif len(args.files) == 2:
+        try:
+            before = open(args.files[0], encoding="utf-8").read()
+            after = open(args.files[1], encoding="utf-8").read()
+        except OSError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        label = args.files[1]
+    else:
+        parser.print_usage(sys.stderr)
+        return 2
+
+    rows = derive_row_set(before, after)
+    print(f"governing-chain-diff: {label}")
+    print(f"derived row set: {len(rows)}")
+    for row in rows:
+        print(f"  [{row.reason}] {normalize(row.text)[:110]}")
+        if row.reason == "governing-chain-changed":
+            print(f"      before chain: {' > '.join(c[:44] for c in row.before_chain)}")
+            print(f"      after  chain: {' > '.join(c[:44] for c in row.after_chain)}")
+    return 1 if rows else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))