@ikon85/agent-workflow-kit 0.10.0

package/scripts/loc_offender_core.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""LoC-offender drive gate — PURE decision core.
+
+The decision logic + structured Loc-Defer parsing. No I/O. The git/subprocess
+adapter + CLI live in loc_offender_gate.py, which imports this module. Splitting
+keeps each file <= the 300-line size gate this very slice enforces.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Band thresholds (changed = added + deleted LoC of the offender file in the slice).
+EXEMPT_LOC = 5  # <= this: trivial touch, exempt
+SUBSTANTIAL_LOC = 30  # >= this: substantial → shrink-or-defer owed; 6..29 = warn
+
+DEFER_REASONS = {"grossfile-partial", "risky-split", "vendored-adjacent", "hotfix"}
+
+
+@dataclass(frozen=True)
+class FileChange:
+    """One file's change in the slice diff (base..head)."""
+
+    path: str  # current (post-rename) repo-root POSIX path
+    old_path: str | None  # pre-rename path, or None if not renamed
+    changed_loc: int  # added + deleted
+    head_lines: int | None  # current line count; None if the file was deleted
+    base_lines: int  # line count at the slice base
+    binary: bool = False  # numstat reported '-'/'-' (unparseable)
+
+
+@dataclass(frozen=True)
+class Defer:
+    """A parsed, well-formed Loc-Defer trailer."""
+
+    file: str
+    reason: str
+    followup: str | None  # e.g. ''
+    reduced_net: int | None
+
+
+@dataclass
+class Verdict:
+    ok: bool = True
+    reds: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def exit_code(self) -> int:
+        return 0 if self.ok else 1
+
+
+def normalize_defer_path(raw: str):
+    """Return (path, error). repo-root POSIX path, leading './' stripped.
+    Absolute paths and parent traversal ('..') are rejected (defer must name a
+    repo-relative offender, never escape the tree)."""
+    p = (raw or "").strip().replace("\\", "/")
+    if not p:
+        return None, "leerer file-Pfad"
+    if p.startswith("/"):
+        return None, f"absoluter Pfad nicht erlaubt: {p}"
+    while p.startswith("./"):
+        p = p[2:]
+    if p == ".." or p.startswith("../") or "/../" in p or p.endswith("/.."):
+        return None, f"Pfad-Traversal ('..') nicht erlaubt: {p}"
+    return p, None
+
+
+def _parse_one(value: str):
+    """Parse one `file=…; reason=…; followup=…; reduced_net=…` trailer value.
+    Return (Defer, error). Syntactic validity only (enum, required-field rule,
+    path); the reduced_net-vs-reality check is semantic → done in evaluate()."""
+    fields: dict[str, str] = {}
+    for part in value.split(";"):
+        part = part.strip()
+        if not part:
+            continue
+        if "=" not in part:
+            return None, f"malformter Trailer-Teil (kein key=value): {part!r}"
+        k, _, val = part.partition("=")
+        fields[k.strip()] = val.strip()
+
+    raw_file = fields.get("file")
+    if not raw_file:
+        return None, f"Loc-Defer ohne file=: {value!r}"
+    path, perr = normalize_defer_path(raw_file)
+    if perr:
+        return None, perr
+
+    reason = fields.get("reason")
+    if reason not in DEFER_REASONS:
+        return None, f"unbekannter reason={reason!r} (erlaubt: {sorted(DEFER_REASONS)})"
+
+    followup = fields.get("followup") or None
+    reduced_raw = fields.get("reduced_net")
+    reduced_net = None
+    if reduced_raw is not None:
+        if not reduced_raw.lstrip("#").isdigit() or int(reduced_raw.lstrip("#")) <= 0:
+            return None, f"reduced_net muss positive Ganzzahl sein, war {reduced_raw!r}"
+        reduced_net = int(reduced_raw)
+
+    if followup is None and reduced_net is None:
+        return None, f"Loc-Defer für {path} braucht followup=#n ODER reduced_net>0"
+
+    return Defer(file=path, reason=reason, followup=followup, reduced_net=reduced_net), None
+
+
+def parse_loc_defer_trailers(values):
+    """Parse all `Loc-Defer:` trailer values from the slice commits.
+    Return (defers, errors). A duplicate `file=` (same offender twice) is an
+    error — ambiguous intent → fail-closed."""
+    defers: list[Defer] = []
+    errors: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        defer, err = _parse_one(value)
+        if err:
+            errors.append(err)
+            continue
+        if defer.file in seen:
+            errors.append(f"doppelter Loc-Defer für {defer.file} — mehrdeutig.")
+            continue
+        seen.add(defer.file)
+        defers.append(defer)
+    return defers, errors
+
+
+def _defer_covers(defer: Defer, change: FileChange) -> tuple[bool, str | None]:
+    """Semantic check: does this (already syntactically-valid) defer actually cover
+    the change? Returns (ok, error). reduced_net may not over-declare the real
+    reduction; grossfile-partial needs reduced_net >= changed OR a followup."""
+    actual_reduction = (change.base_lines - change.head_lines) if change.head_lines is not None else change.base_lines
+    if defer.reduced_net is not None and defer.reduced_net > actual_reduction:
+        return False, (
+            f"{defer.file}: reduced_net={defer.reduced_net} über-deklariert "
+            f"(reale Reduktion {actual_reduction}).")
+    if defer.reason == "grossfile-partial":
+        meets_reduced = defer.reduced_net is not None and defer.reduced_net >= change.changed_loc
+        if not meets_reduced and not defer.followup:
+            return False, (
+                f"{defer.file}: grossfile-partial verlangt reduced_net >= "
+                f"{change.changed_loc} (changed) ODER followup.")
+    return True, None
+
+
+def offender_key(change: FileChange) -> str:
+    """The baseline path a change is matched against: the OLD path on a rename
+    (the offender was listed under its pre-rename path), else the current path."""
+    return change.old_path or change.path
+
+
+def evaluate(changes, offenders, defers, max_lines, defer_errors=None) -> Verdict:
+    """Pure decision over the slice diff. Red if any substantial offender touch
+    is neither shrunk nor validly deferred. A non-empty `defer_errors` (malformed/
+    duplicate trailers from parse_loc_defer_trailers) is a global fail-closed red."""
+    v = Verdict()
+    for err in defer_errors or []:
+        v.ok = False
+        v.reds.append(f"malformter Loc-Defer-Trailer → fail-closed: {err}")
+    by_key = {d.file: d for d in defers}
+    for ch in changes:
+        key = offender_key(ch)
+        if key not in offenders:
+            continue
+        # Binary/unparseable numstat is checked FIRST: collect_changes reports
+        # changed_loc=0 for a binary file, so a band check would exempt it before
+        # this defensive fail-closed could fire. (Should never hit for .ts/.tsx.)
+        if ch.binary:
+            v.ok = False
+            v.reds.append(f"{key}: binäres/unparsebares numstat für einen Offender → fail-closed.")
+            continue
+        if ch.changed_loc <= EXEMPT_LOC:
+            continue
+        if ch.changed_loc < SUBSTANTIAL_LOC:
+            v.warnings.append(
+                f"{key}: {ch.changed_loc} LoC geändert (6–{SUBSTANTIAL_LOC - 1} = "
+                "Warnung) — beim nächsten substanziellen Touch schrumpfen.")
+            continue
+        # Substantial touch (>= SUBSTANTIAL_LOC).
+        if ch.head_lines is None:  # deleted = best possible shrink
+            continue
+        if ch.head_lines <= max_lines or ch.head_lines < ch.base_lines:
+            continue  # under the limit, or net-shrunk → green (prune enforced by)
+        # Still > max_lines, no net shrink → needs a valid defer.
+        defer = by_key.get(key)
+        if defer is not None:
+            covers, derr = _defer_covers(defer, ch)
+            if covers:
+                continue
+            v.ok = False
+            v.reds.append(derr)
+            continue
+        v.ok = False
+        v.reds.append(
+            f"{key} ({ch.head_lines}>{max_lines}) ≥{SUBSTANTIAL_LOC} LoC angefasst, "
+            "nicht geschrumpft, kein Loc-Defer.")
+    return v

package/scripts/loc_offender_gate.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""LoC-offender drive gate — git/subprocess adapter + CLI.
+
+Thin shell over the pure core in loc_offender_core.py. Invoked by .githooks/pre-push
+as `loc_offender_gate.py --check --head <local_sha> [--base-ref <ref>]`, once per
+non-delete pushed branch ref. Exit 1 = red (push blocked). Pure logic + its tests
+live in loc_offender_core.py.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from loc_offender_core import (
+    FileChange,
+    Verdict,
+    evaluate,
+    parse_loc_defer_trailers,
+)
+
+class GateError(RuntimeError):
+    """A condition the gate cannot evaluate → fail-closed (exit 1)."""
+
+
+def _git(args, cwd=None) -> str:
+    r = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
+    if r.returncode != 0:
+        raise GateError(f"git {' '.join(args)}: {r.stderr.strip()}")
+    return r.stdout
+
+
+def _ref_exists(ref: str, cwd=None) -> bool:
+    return subprocess.run(["git", "rev-parse", "--verify", "--quiet", ref],
+                          cwd=cwd, capture_output=True).returncode == 0
+
+
+def resolve_base_ref(explicit, cwd=None) -> str:
+    """origin/HEAD → origin/main → fail-closed. An explicit --base-ref wins if valid."""
+    if explicit:
+        if _ref_exists(explicit, cwd):
+            return explicit
+        raise GateError(f"--base-ref {explicit!r} nicht auflösbar.")
+    head = subprocess.run(["git", "rev-parse", "--abbrev-ref", "origin/HEAD"],
+                          cwd=cwd, capture_output=True, text=True)
+    if head.returncode == 0 and head.stdout.strip():
+        return head.stdout.strip()
+    if _ref_exists("origin/main", cwd):
+        return "origin/main"
+    raise GateError("keine base-ref auflösbar (origin/HEAD, origin/main fehlen) → fail-closed.")
+
+
+def load_max_lines(path=None):
+    """Read maxLines + offenders set from max-lines-allowlist.json (the single SSOT).
+
+    Missing file / malformed JSON / missing keys → GateError, not a bare
+    exception — run_gate's `except GateError` already turns that into a normal
+    red gate message (with the SKIP_CI_GUARDS escape hatch) instead of a raw
+    traceback escaping the gate.
+    """
+    p = Path(path) if path else _repo_root() / "max-lines-allowlist.json"
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+        return int(raw["maxLines"]), set(raw["offenders"])
+    except GateError:
+        raise
+    except Exception as exc:
+        raise GateError(f"max-lines-allowlist.json unlesbar/ungültig ({p}): {exc}") from exc
+
+
+def _repo_root() -> Path:
+    return Path(_git(["rev-parse", "--show-toplevel"]).strip())
+
+
+def _count_lines_at(rev: str, path: str, cwd=None):
+    """wc -l style count of <rev>:<path>; None if the path does not exist there."""
+    r = subprocess.run(["git", "show", f"{rev}:{path}"], cwd=cwd, capture_output=True, text=True)
+    if r.returncode != 0:
+        return None
+    body = r.stdout
+    if body == "":
+        return 0
+    return len(body[:-1].split("\n")) if body.endswith("\n") else len(body.split("\n"))
+
+
+def parse_numstat_z(raw: str):
+    """Parse `git diff --numstat -z --find-renames` into (added, deleted, old_path, path).
+    -z record: `A\\tD\\tpath\\0` normally; `A\\tD\\t\\0from\\0to\\0` for renames;
+    `-` for added/deleted on binary files."""
+    toks = raw.split("\0")
+    i, out = 0, []
+    while i < len(toks):
+        field = toks[i]
+        if field == "":
+            i += 1
+            continue
+        added, deleted, inline = (field.split("\t") + ["", "", ""])[:3]
+        if inline == "":  # rename → next two tokens are from, to
+            old_path, path = toks[i + 1], toks[i + 2]
+            i += 3
+        else:
+            old_path, path = None, inline
+            i += 1
+        out.append((added, deleted, old_path, path))
+    return out
+
+
+def collect_changes(base: str, head: str, offenders, cwd=None):
+    """Build FileChange entries for diff files that touch an offender (matched by
+    old path on rename). Non-offender files are skipped (no git line-count calls)."""
+    raw = _git(["diff", "--numstat", "-z", "--find-renames", base, head], cwd=cwd)
+    changes = []
+    for added, deleted, old_path, path in parse_numstat_z(raw):
+        key = old_path or path
+        if key not in offenders:
+            continue
+        binary = added == "-" or deleted == "-"
+        changed = 0 if binary else int(added) + int(deleted)
+        base_lines = _count_lines_at(base, key, cwd) or 0
+        head_lines = _count_lines_at(head, path, cwd)
+        changes.append(FileChange(path=path, old_path=old_path, changed_loc=changed,
+                                  head_lines=head_lines, base_lines=base_lines, binary=binary))
+    return changes
+
+
+def collect_defer_values(base: str, head: str, cwd=None):
+    """All `Loc-Defer:` trailer values across the slice commits (real trailer block,
+    via git's own parser — not a %B body grep)."""
+    out = _git(["log", f"{base}..{head}",
+                "--format=%(trailers:key=Loc-Defer,valueonly,unfold)"], cwd=cwd)
+    return [ln.strip() for ln in out.splitlines() if ln.strip()]
+
+
+DEFAULT_MAX_LINES = 300  # only the fallback when the allowlist itself is unreadable
+
+
+def run_gate(head: str, base_ref=None, cwd=None):
+    """Resolve base, collect the slice diff + defers, evaluate. GateError → red.
+    Returns (Verdict, max_lines) so the caller's repair message needs no re-read."""
+    max_lines = DEFAULT_MAX_LINES
+    try:
+        ref = resolve_base_ref(base_ref, cwd)
+        base = _git(["merge-base", ref, head], cwd=cwd).strip()
+        max_lines, offenders = load_max_lines()
+        changes = collect_changes(base, head, offenders, cwd)
+        defers, errors = parse_loc_defer_trailers(collect_defer_values(base, head, cwd))
+        return evaluate(changes, offenders, defers, max_lines, defer_errors=errors), max_lines
+    except GateError as exc:
+        v = Verdict(ok=False)
+        v.reds.append(f"{exc} → fail-closed (Notausgang: SKIP_CI_GUARDS=1 git push).")
+        return v, max_lines
+
+
+_REPAIR = (
+    "→ schrumpfen (≤{max}) ODER Aufschub:\n"
+    '   git commit --amend --trailer "Loc-Defer: file=<pfad>; reason=grossfile-partial; followup=#NNN"\n'
+    "→ Notausgang: SKIP_CI_GUARDS=1 git push")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="loc_offender_gate.py", description=__doc__.splitlines()[0])
+    ap.add_argument("--check", action="store_true", help="run the gate (exit 1 = red)")
+    ap.add_argument("--head", required=True, help="pushed commit SHA (the slice head)")
+    ap.add_argument("--base-ref", dest="base_ref", help="integration base ref (default: origin/HEAD→origin/main)")
+    args = ap.parse_args(argv)
+
+    v, max_lines = run_gate(args.head, args.base_ref)
+    for w in v.warnings:
+        print(f"⚠ LoC-Offender: {w}")
+    if v.ok:
+        return 0
+    print("🔴 LoC-Offender-Gate — Push blockiert:")
+    for r in v.reds:
+        print(f"   {r}")
+    print(_REPAIR.format(max=max_lines))
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/node_kind.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""node_kind.py — pure node-kind classifier shared by execute-ready-check.py
+.
+
+execute-ready-check.py used to infer "is this an anchor?" structurally (no
+native parent + has children). That heuristic breaks the moment an anchor gets
+a NATIVE parent of its own — a Welle-Anker promoted under a Programm-PRD, or
+the Programm-PRD itself: the checker would climb to the parent and audit the
+anchor as if it were a plain leaf, forcing a bucket + rev-match on itself and
+on its sibling anchors (which don't carry a bucket by design).
+
+This module replaces that heuristic with an EXPLICIT classification, read off
+the node's own labels/body — never off its position in the graph:
+
+  program   — `<!-- prd: program -->` body marker. Highest precedence (a
+              distinct object, wins over any label a Programm-PRD might also
+              carry). Deliberately marker-only — the `type:program` label is a
+              LATER slice's addition; this module needs no profile key
+              for it and must keep working before that label exists.
+  anchor    — `type:cluster` label. Wins over `wave-stub` when a node somehow
+              carries both (a drift/transition state) — mirrors the
+              to-prd/to-issues precedence ("type:cluster stops always; Wave
+              stops unless wave-stub").
+  wave_stub — `wave-stub` label (a board-to-waves candidate stub, OR an
+              un-promoted Stufe-1p program stub — same label, two
+              provenances, both structurally "not yet an anchor").
+  leaf      — none of the above; an ordinary slice/child issue.
+
+ROOT_KINDS = {program, anchor}: execute-ready-check.py evaluates these at
+their OWN local root (their own children as siblings) and never lifts them to
+a real parent, even when one exists. The multi-level, programme-wide graph
+validation is validate-graph's job — this stays
+rooted-local (target + at most one level of children).
+
+Pure + I/O-free by design (mirrors anchor_table.py) — directly unit-tested
+with plain dicts, no gh/board_config coupling.
+"""
+from __future__ import annotations
+
+import re
+
+PROGRAM = "program"
+ANCHOR = "anchor"
+WAVE_STUB = "wave_stub"
+LEAF = "leaf"
+
+ROOT_KINDS = frozenset({PROGRAM, ANCHOR})
+
+PROGRAM_MARKER_RE = re.compile(r"<!--\s*prd:\s*program\s*-->")
+
+
+def classify_node(node: dict, *, cluster_type_label: str | None,
+                   wave_stub_label: str | None) -> str:
+    """program | anchor | wave_stub | leaf for `node` ({body, labels, ...}).
+
+    `cluster_type_label`/`wave_stub_label` come from the board profile
+    (`_CFG["labels"].get(...)`) — passed in rather than read here so this
+    module stays board-profile-free and directly testable.
+    """
+    body = node.get("body") or ""
+    labels = node.get("labels") or []
+    if PROGRAM_MARKER_RE.search(body):
+        return PROGRAM
+    if cluster_type_label and cluster_type_label in labels:
+        return ANCHOR
+    if wave_stub_label and wave_stub_label in labels:
+        return WAVE_STUB
+    return LEAF

package/scripts/portability_profile_scan.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""portability_profile_scan.py — profile-VALUE literal scan (#1878, Welle 49
+Slice 7, extends the portability lint in test_skill_portability_lint.py).
+
+A published (generic/vendored) skill body must reference the board profile
+(`docs/agents/board-sync.md`, loaded by `board_config.py`) by KEY —
+`prMarkers.retroValues`, `headings.vorBau` — never MANDATE the literal VALUE
+a profile happens to configure (e.g. testreporter's `gefahren`/`übersprungen`,
+`Vor Bau zu klären`). A consumer whose profile configures different words
+silently fails a skill that hardcoded testreporter's wording as required —
+the same drift class `test_skill_portability_lint.py`'s CONSTANT_PATTERNS
+scan already closes for opaque board node/option ids; this closes it for the
+human-facing convention words instead.
+
+A line that also names the profile key is a reference, not a hardcode —
+exempt (mirrors CONSTANT_PATTERNS' own exempt rule). A line carrying
+`portability-lint: ok` is exempt too (deliberate doc example, e.g. a
+copy-paste-ready marker/heading example where inlining the key would corrupt
+the example).
+"""
+from __future__ import annotations
+
+import re
+
+EXEMPT = "portability-lint: ok"
+
+# (label, literal pattern, profile-key substring whose presence on the same
+# line exempts the match — a reference, not a hardcode).
+PROFILE_VALUE_PATTERNS = [
+    # prMarkers.retroValues — the two configured PR "**Retro:**"-line words.
+    # Backtick-quoted only: bare "gefahren"/"übersprungen" are ordinary German
+    # words (past participles of fahren/überspringen) outside this
+    # convention — unquoted would false-positive on normal prose (e.g. "Retro
+    # schon gefahren?").
+    ("prMarkers.retroValues literal", re.compile(r"`(?:gefahren|übersprungen)`"), "retroValues"),
+    # headings.vorBau — the configured HITL heading text. The phrase is
+    # specific enough that no quoting requirement is needed.
+    ("headings.vorBau literal", re.compile(r"Vor Bau zu klären"), "vorBau"),
+]
+
+
+def find_profile_value_literals(text: str) -> list[tuple[int, str, str]]:
+    """Return (line_no, label, line) for every hardcoded MANDATORY profile-value
+    literal, minus lines that also reference the profile key (a profile-driven
+    reference, not a hardcode) or carry the exempt marker."""
+    out = []
+    for n, line in enumerate(text.splitlines(), 1):
+        if EXEMPT in line:
+            continue
+        for label, pattern, key in PROFILE_VALUE_PATTERNS:
+            if pattern.search(line) and key not in line:
+                out.append((n, label, line.strip()))
+    return out