@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/wrapup/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: wrapup
+disable-model-invocation: true
+"description": "Use ONLY when the user types /wrapup. Session-end \"land & clean\" for a finished feature/fix worktree — merges the open PR (= triggers prod deploy), kills the worktree dev server, removes the worktree + local branch, and fast-forwards the main checkout so main is current again, then sweeps merged-branch leftovers (local + stale remote whose PR is merged). If the slice isn't landed yet, it first makes it landable (Step 0): commits a dirty tree (after an .env/secret check), pushes, and opens the PR — reusing one if it already exists. User-triggered only (never auto-invoke, never hook). Aborts hard only on: not in a feature worktree, a detected .env/secret, a rejected push, a conflicting PR, or red (FAILURE) checks."
+---
+
+# wrapup — land PR & tear down worktree
+
+Trigger: user types `/wrapup` (optionally with a PR number). **Manual only** — `disable-model-invocation: true`, no hook, no auto-invoke.
+
+## ⚠ Spec context
+
+**Merging to `main` = prod deploy.** The agent never deploys on its own — the user's `/wrapup` input IS the explicit merge+deploy authorization for that run. Never call this skill from a hook, another skill, or autonomously. Deploy banner before the merge, no y/n confirmation (deliberate); the pre-flight hard stops are non-negotiable.
+
+## Execution model — script does mechanics, the agent does judgment
+
+All enumerable git/gh plumbing lives in **`scripts/wrapup-land.py`** (`preflight` / `commit` / `land`, JSON report on stdout, exit 1 = STOP with reason in the JSON). It replaces the former Sonnet phase-2 subagent — measured over 120 runs the subagent burned a median 23 model turns on steps with zero judgment content (→ mechanized 2026-07).
+
+The agent keeps: retro gate, secret review, commit message, PR body text, drift-fallback candidates, sibling propagation, anchor close, final report — plus **diagnosis whenever the script STOPs**. On any STOP: fix the named cause, re-run (the script is idempotent). **Force NOTHING** — no `--force`, no `-D`, no `--no-verify`.
+
+## Flow
+
+### 1 · Pre-flight
+Run **in the worktree**:
+```bash
+python3 scripts/wrapup-land.py preflight
+```
+Hard stop (the only pure precondition): not in a feature worktree / on `main` — the script exits 1. The report carries everything the later steps need: dirty files, `.env` hits, secret-grep hits, issue + parent (leaf vs. anchor slice), existing PR + whether its body has a `**Retro:**` line, parsed `ANNAHMEN.md` drift lines, profile values (`retro_values`, `vor_bau`, remote-sweep switch).
+
+### 2 · Retro gate (blocking, optional retro-exit — before anything is committed)
+One reminder, not a merge confirmation:
+> "Already ran a retro? **(a)** yes / continue → landing now. **(b)** you want one first → clean abort here, run `/retro`, then `/wrapup` again — repo-file patches then travel in this PR."
+
+(b) → exit cleanly, touch nothing (a skill can't pause/resume another skill). **Never auto-run `/retro`.** The answer materializes as the mandatory `**Retro:**` PR-body line in step 4 — that's recording, not a second question. Why the gate lives here: in a foreign project this is the only portable retro touchpoint; a project-local "offer retro before PR" convention usually answers it already.
+
+### 3 · Commit (only if the tree is dirty)
+Judgment first, then the guarded commit:
+- **Secret review:** judge the preflight `secret_hits` — a variable *named* `token` isn't a secret; a real key → resolve first, never commit. `.env` files are a mechanical hard block inside the script.
+- **Commit message:** conventional, `<type>(<scope>): <summary> (#<issue>)` — type from the branch prefix, summary from the actual diff, issue from the branch.
+```bash
+python3 scripts/wrapup-land.py commit -m "<message>"   # --allow-matches only after judging every hit a false positive
+```
+STOP on hook failure: many `Cannot find module`/TS2307 across **unrelated** files in a node/pnpm repo = stale worktree `node_modules` → `pnpm install --frozen-lockfile`, re-run. Real errors in slice files = legitimate stop. **Never `--no-verify`.**
+
+### 4 · Author the PR body (agent-written, script-checked)
+Write title + body to a temp file (inline bodies with backticks crash bash):
+- Leaf issue → `closes #<n>`, **never inside backticks** (GitHub ignores the keyword there). Wave/cluster slice → `Part of #<anchor>`, **never `closes`** (would close the anchor early).
+- **Mandatory `**Retro:**` line** — exactly one of the two `retro_values` from the preflight report (closed set, copy verbatim; `pr-body-check.py` rejects anything else): retro ran → `**Retro:** <value0> — findings under ## Retro / Meta-Findings`; skipped → `**Retro:** <value1> — <reason>`. "Nothing to retro" is the second value + reason, not a third form. Applies to every PR body, including ad-hoc `gh pr create` mid-session.
+- **Assumption drift:** the build-time log `ANNAHMEN.md` is explicitly captured content — its well-formed lines become `annahme-drift` markers **mechanically, no confirmation gate** (`land` merges them into the body; decision 2026-07-06, replaced the old propose+confirm for log entries). Two cases stay with the agent:
+  - **Malformed line** (no `#<n>` target) → clarify with the user (fix the target or discard deliberately), never drop silently; `--skip-malformed-drift` only for a deliberately discarded rest.
+  - **No log / empty log** → fallback, retro-style: walk the slice's deliberately made or reversed assumptions yourself and present **named candidates** (`- #<n>?: <assumption> → might carry <issue>`); user confirms → write the markers into the body by hand. Zero candidates → say so explicitly ("no drift found — checked: <what>"). The log is the floor, not the ceiling — drift noticed while landing goes in the same way.
+
+### 5 · Land
+Run **from the main tree** (the script refuses inside the worktree — an in-worktree shell would survive teardown and the process kill):
+```bash
+python3 scripts/wrapup-land.py land --branch "<branch>" --title "<title>" --body-file /tmp/wrapup-pr-body.md
+```
+One call covers: push → PR create/reuse (+ drift markers merged into the body) → `pr-body-check.py` gate (exit 1 = STOP, exit 2 = fail-open warning) → merge gate (red check / `CONFLICTING` = STOP; fresh-PR `UNKNOWN` mergeable passes — the merge itself is the real gate) → **merge** (`--merge` + `--delete-branch`, verified `MERGED`) → dev-server kill (`.dev-ports` ports + cwd-under-worktree walk, own shell ancestry excluded) → worktree remove (no `--force`; refusal = STOP, check surviving processes first) → main `--ff-only` pull + `branch -d` → issue-close verify (auto-close misses are closed manually) → local merged-branch sweep (`-d` only — squash/rebase-merged branches stay a manual call by design) → remote merged-PR sweep (opt-in `wrapup.remoteBranchSweep` in the board profile; PR-status-authoritative via `ls-remote`; deleted remote branches are restorable from the PR page) → anchor-sync (dry-run diff in the report) + anchor completeness check + `execute-ready-check --mode audit` → **upward propagation:** if the anchor's native parent is a Program-PRD, `program-sync` refreshes its Wellenplan (Status + Issue cells) and checks off mechanically completed Phasen-Gates — the slice event is visible at the program level, not only in the wave (`program_sync` block in the report; skipped when the parent isn't a program).
+
+STOP → diagnose in the main conversation, fix, re-run `land` (an already-merged PR resumes at teardown).
+
+### 6 · Post-merge (agent)
+- **Deploy banner**, one line: `⚠ PR #<pr> merged → main deploys (~7 min live).`
+- **Sibling propagation:** for each `drift_markers` entry in the land report, append the note to the target issue's `vor_bau` section + re-stamp its `plan_revision`. Log-based markers → **write directly, then show what was written where** (mandatory report — visibility moved from a pre-gate into the report, decision 2026-07-06); fallback candidates the user hasn't confirmed yet → confirm first. Program context widens the target set to unbuilt wave-stubs/leaves and the Program-PRD itself — same append-only mechanism. **Exception:** appends to the Program-PRD or unbuilt wave-stubs do **not** re-stamp `plan_revision` — that stays reserved for structural wave-plan edits via the `to-waves` escalation path; a mere drift note must not stale-block published stubs.
+- **Anchor close:** report says `anchor_complete: true` → `gh issue close <anchor> -c "Wave complete — all slices merged via PR #<pr>."` and verify board status Done. The guard keeps anchors away from every auto-close — this verified close is the only close path; without it the anchor stays silently open after the last slice. **Then re-run the upward propagation**: the land-time `program-sync` ran BEFORE this close, so on a wave-completing slice the Wellenplan still shows 🔄 and the Phasen-Gate stays unchecked — after the board shows Done, run `python3 scripts/board-sync.py program-sync <program-prd#>` once more (the report's `program_sync.program` names it; skip when the report says the parent is not a program). Board auto-rules can lag the close (Close→Done race) — verify Done first, that's what the token reads.
+- **Report**, concise, from the land JSON: PR merged · issue close (auto/manual) · worktree removed · branch deleted · sweep counts local/remote · anchor synced + complete/pending · program propagation (`program_sync`: Wellenplan refreshed / gates checked / skipped) · propagation writes (what → where) · `main` at `<sha>` · deploy running.
+
+## Out of scope
+- Live-verify / DoD: must happen **before** `/wrapup` — this skill lands, it does not verify.
+- `/retro`: offered before landing (step 2), never run by this skill.
+- Other worktrees / their servers stay untouched.

package/.agents/skills/wrapup/SOURCES.txt

@@ -0,0 +1,6 @@
+# Source-Anker für skill-drift-hint.py. Repo-relative Pfade, einer pro Zeile.
+# Bewegt sich eine Quelle in git nach dem letzten SKILL.md-Commit → Freshness-Warnung.
+scripts/wrapup-land.py
+scripts/pr-body-check.py
+scripts/board-sync.py
+scripts/board_config.py

package/.agents/skills/zoom-out/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: zoom-out
+description: "Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture."
+disable-model-invocation: true
+---
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. (For a full refactor/deepening pass with an HTML report and grilling loop, use `improve-codebase-architecture` instead.)

package/.agents/skills/zoom-out/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/zoom-out` @ 2bf7005, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.claude/hooks/_hook_utils.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+Shared helpers for .claude/hooks/*.py — logging, subprocess wrappers,
+git inspection. Underscore-prefix signals "not a hook, not invoked by
+Claude Code directly".
+
+Python adds the script directory to sys.path automatically, so any hook
+in this folder can `from _hook_utils import ...`.
+
+Migration notes for hook refactors:
+- `log(name, msg)` takes two args (per-hook name + message). Callers must
+  pass their hook name as the first arg — there is no implicit per-module
+  log-file binding. Recommended pattern: `HOOK_NAME = "<hook-name>"` as a
+  module-level constant in each hook, then `log(HOOK_NAME, msg)` at the
+  call sites.
+- `run()` is silent-on-failure: exceptions return "" without logging. The
+  pre-refactor `run()` in some hooks (notably enforce-worktree-cwd.py)
+  logged `"exec failed: ..."` on subprocess exception. That diagnostic
+  log is intentionally dropped — git/subprocess crashes are rare and the
+  meaningful Audit-log entries (`BLOCKED cmd=...`) still get written.
+"""
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+# Resolved relative to CWD at call time. Hooks are invoked from repo root
+# (or from a linked worktree root), so this resolves to <root>/.claude/logs.
+LOG_DIR = Path(".claude/logs")
+
+
+def rotate_log_if_needed(log_path: Path, max_bytes: int = 100_000, generations: int = 3) -> None:
+    """
+    If log_path exceeds max_bytes, rotate it: .log → .log.1 → .log.2 → ... → .log.<generations>,
+    oldest dropped. Silent-on-failure.
+    """
+    try:
+        if not log_path.exists():
+            return
+        if log_path.stat().st_size <= max_bytes:
+            return
+        # Drop the oldest generation
+        oldest = log_path.with_suffix(log_path.suffix + f".{generations}")
+        if oldest.exists():
+            oldest.unlink()
+        # Shift .log.<N-1> → .log.<N>, ..., .log.1 → .log.2
+        for n in range(generations - 1, 0, -1):
+            src = log_path.with_suffix(log_path.suffix + f".{n}")
+            dst = log_path.with_suffix(log_path.suffix + f".{n+1}")
+            if src.exists():
+                src.rename(dst)
+        # .log → .log.1
+        log_path.rename(log_path.with_suffix(log_path.suffix + ".1"))
+    except Exception:
+        pass  # silent
+
+
+def log(name: str, msg: str) -> None:
+    """
+    Append `<ISO-timestamp> <msg>\\n` to .claude/logs/<name>.log. Creates
+    LOG_DIR if missing. Rotates first if file exceeds 100 KB. Silent-on-failure.
+    """
+    try:
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        log_file = LOG_DIR / f"{name}.log"
+        rotate_log_if_needed(log_file)
+        with log_file.open("a", encoding="utf-8") as f:
+            f.write(f"{datetime.now().isoformat(timespec='seconds')} {msg}\n")
+    except Exception:
+        pass
+
+
+def run(cmd: list[str], timeout: int = 5) -> str:
+    """
+    Wrapper around subprocess.run. Returns stdout.strip() on success, "" on any failure.
+    Failures are NOT logged here (caller decides whether to log).
+    """
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return r.stdout.strip()
+    except Exception:
+        return ""
+
+
+def run_with_status(cmd: list[str], timeout: int = 15) -> tuple[int, str]:
+    """
+    Wrapper that returns (returncode, stdout) — for hooks that branch on exit code.
+    Returns (-1, "") on exception.
+    """
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return r.returncode, r.stdout
+    except Exception:
+        return -1, ""
+
+
+def is_main_worktree() -> bool:
+    """True if GIT_DIR == GIT_COMMON_DIR (= main tree, not a linked worktree)."""
+    git_dir = run(["git", "rev-parse", "--git-dir"])
+    git_common = run(["git", "rev-parse", "--git-common-dir"])
+    if not git_dir or not git_common:
+        return False
+    try:
+        return Path(git_dir).resolve() == Path(git_common).resolve()
+    except Exception:
+        return False
+
+
+def current_branch() -> str:
+    """Returns current branch name or "" if detached/not a repo."""
+    return run(["git", "branch", "--show-current"])
+
+
+_BRANCH_ISSUE_RE = re.compile(r"^(?:feat|fix)/(\d+)-")
+
+
+def parse_issue_from_branch(branch: str):
+    """Issue number (str) from a `feat/<n>-…` / `fix/<n>-…` branch, else None.
+    Shared so hooks don't each re-declare the convention regex."""
+    m = _BRANCH_ISSUE_RE.match(branch or "")
+    return m.group(1) if m else None
+
+
+def repo_root() -> str:
+    """Returns repo root or "" if not a repo."""
+    return run(["git", "rev-parse", "--show-toplevel"])
+
+
+def is_git_ignored(path: str) -> bool:
+    """True if `path` is git-ignored (safe to edit anywhere — never enters a commit).
+
+    Uses `git check-ignore -q`: exit 0 = ignored, 1 = not ignored, 128 = error.
+    Only exit 0 counts as ignored; on not-matched OR error we return False so the
+    caller errs toward enforcing discipline rather than silently allowing an edit.
+    Caveat: a force-added tracked file that also matches an ignore pattern reports
+    ignored — acceptable, that combination is vanishingly rare in this repo.
+    """
+    if not path:
+        return False
+    rc, _ = run_with_status(["git", "check-ignore", "-q", "--", path], timeout=5)
+    return rc == 0
+
+
+def has_feature_worktrees() -> bool:
+    """True if at least one linked worktree exists with a non-main branch."""
+    output = run(["git", "worktree", "list", "--porcelain"])
+    if not output:
+        return False
+    for block in output.split("\n\n"):
+        m = re.search(r"^branch refs/heads/(.+)$", block, re.MULTILINE)
+        if m:
+            branch = m.group(1).strip()
+            if branch and branch not in ("main", "master"):
+                return True
+    return False
+
+
+def count_worktrees() -> int:
+    """Total number of worktrees (incl. main)."""
+    output = run(["git", "worktree", "list"])
+    if not output:
+        return 0
+    return len([line for line in output.splitlines() if line.strip()])
+
+
+def normalize_to_repo_relative(file_path: str, root: str) -> str | None:
+    """
+    Converts absolute paths to repo-relative paths.
+    - Relative passthrough.
+    - Absolute inside root: relative-to-root.
+    - Absolute outside root or empty input: None.
+    """
+    if not file_path:
+        return None
+    p = Path(file_path)
+    if not p.is_absolute():
+        return file_path
+    if not root:
+        return None
+    try:
+        rel = p.resolve().relative_to(Path(root).resolve())
+        return str(rel)
+    except ValueError:
+        return None

package/.claude/hooks/drift-guard.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Drift-Guard — PreToolUse block on Write|Edit|MultiEdit of a handoff doc when the
+linked GitHub issue's rooted graph is not execute-ready.
+
+Why a hook (not skill prose): the `handoff` skill AND the global
+`grill-with-docs-codex` live OUTSIDE the repo. Only a repo-side hook fires
+regardless of which global skill triggered the Write — the single repo-side net
+covering the -codex path.
+
+Coverage (honestly bounded): fires at the handoff / session-boundary Write.
+NOT a board-wide scan, NOT a "grill-exit" event (no clean tool hook for that).
+Accepted gap: Bash redirect / tee / cp into `.handoff/` is not covered — the
+threat model is "skill/agent forgot", not an adversary; handoff writes via Write.
+
+Mechanism: self-filters to `.handoff/*.md`; extracts the issue (content anchor
+first, filename fallback); delegates ALL coherence to scripts/execute-ready-check.py
+(--mode handoff). Deny = exit 2 + stderr (house pattern: enforce-worktree.py,
+block-secrets.py). Override: a deliberate `<!-- guard-ack: #<n> r<N> reason:… by-user -->`
+in the content. fail-closed once a target is parsed (the checker enforces that);
+fail-OPEN when no handoff target is identifiable (not the stale handoff we guard).
+
+Audit log: .claude/logs/drift-guard.log
+"""
+import importlib.util
+import json
+import re
+import sys
+from pathlib import Path
+
+from _hook_utils import log
+
+HOOK_NAME = "drift-guard"
+HANDLED_TOOLS = {"Write", "Edit", "MultiEdit"}
+HANDOFF_PATH_RE = re.compile(r"/\.handoff/[^/]*\.md$")
+ISSUE_ANCHOR_RE = re.compile(r"/issues/(\d+)")          # content-first: [#n](…/issues/n)
+FILENAME_ISSUE_RE = re.compile(r"(\d+)\.md$")           # fallback: <date>-<n>.md
+# Override must be issue-scoped, rev-scoped, reasoned, by-user (Codex R1 — not the cheap `known`).
+GUARD_ACK_RE = re.compile(r"<!--\s*guard-ack:\s*#?\d+\s+r\d+\s+reason:.+\bby-user\s*-->",
+                          re.IGNORECASE | re.DOTALL)
+
+# Load the shared checker (hyphenated filename → importlib). Repo root = parents[2].
+_CHECKER_PATH = Path(__file__).resolve().parents[2] / "scripts" / "execute-ready-check.py"
+
+
+_CHECKER = None
+
+
+def _load_checker():
+    """Load + cache the shared checker (module exec is not free — load once per
+    process, not once per call site)."""
+    global _CHECKER
+    if _CHECKER is None:
+        spec = importlib.util.spec_from_file_location("execute_ready_check", _CHECKER_PATH)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        _CHECKER = mod
+    return _CHECKER
+
+
+def is_handoff_write(payload: dict) -> bool:
+    if payload.get("tool_name") not in HANDLED_TOOLS:
+        return False
+    fp = (payload.get("tool_input") or {}).get("file_path", "")
+    return bool(HANDOFF_PATH_RE.search(fp))
+
+
+def extract_content(payload: dict) -> str:
+    ti = payload.get("tool_input") or {}
+    tool = payload.get("tool_name")
+    if tool == "Write":
+        return ti.get("content", "") or ""
+    if tool == "Edit":
+        return ti.get("new_string", "") or ""
+    if tool == "MultiEdit":
+        return "\n".join((e or {}).get("new_string", "") for e in ti.get("edits", []) or [])
+    return ""
+
+
+def extract_issue(payload: dict, content: str):
+    # Content anchor first, filename fallback. Deliberately NO branch fallback:
+    # a meta/tooling handoff carries no issue (handoff skill supports this) and
+    # must fail-open; a branch-based guess would mis-attribute the branch's issue
+    # and false-block. None here → should_block() allows (not the stale handoff we guard).
+    m = ISSUE_ANCHOR_RE.search(content or "")
+    if m:
+        return int(m.group(1))
+    fp = (payload.get("tool_input") or {}).get("file_path", "")
+    m = FILENAME_ISSUE_RE.search(fp)
+    if m:
+        return int(m.group(1))
+    return None
+
+
+def run_check(issue: int, intent: str) -> dict:
+    """Delegate to the shared checker. Isolated so tests can patch it."""
+    try:
+        checker = _load_checker()
+        return checker.build_and_evaluate(issue, "handoff", intent)
+    except Exception as e:
+        # checker itself unavailable → fail-closed (a target was identified)
+        log(HOOK_NAME, f"checker load/exec failed: {e} → fail-closed")
+        return {"deny_recommended": True, "graph_coherent": False,
+                "target_buildable": False, "grandfathered": None,
+                "violations": [f"#{issue}: checker unavailable ({e}) — fail-closed"]}
+
+
+def _infer_intent(content: str) -> str:
+    try:
+        return _load_checker().infer_intent(content)
+    except Exception:
+        return "build"
+
+
+def should_block(payload: dict):
+    """Returns (block: bool, message: str)."""
+    if not is_handoff_write(payload):
+        return False, ""
+    content = extract_content(payload)
+    if GUARD_ACK_RE.search(content):
+        log(HOOK_NAME, "guard-ack override present → allow")
+        return False, ""
+    issue = extract_issue(payload, content)
+    if issue is None:
+        log(HOOK_NAME, "no identifiable issue target → fail-open allow")
+        return False, ""
+    intent = _infer_intent(content)
+    result = run_check(issue, intent)
+    if result.get("deny_recommended"):
+        return True, build_block_message(issue, intent, result)
+    return False, ""
+
+
+def build_block_message(issue: int, intent: str, result: dict) -> str:
+    lines = [f"DRIFT-GUARD — Handoff für #{issue} BLOCKED (nicht execute-ready):", ""]
+    for v in result.get("violations", []):
+        lines.append(f"  · {v}")
+    if intent == "build" and not result.get("target_buildable", True) and result.get("graph_coherent"):
+        lines.append(f"  · #{issue} ist HITL (gültig, aber nicht baubar) — erst grillen, kein /tdd")
+    if result.get("open_blockers"):
+        blocked = ", ".join(f"#{n}" for n in result["open_blockers"])
+        lines.append(f"  · #{issue} ist nativ blockiert durch offene {blocked} "
+                     f"(Blocking-SSOT = Issue-Dependencies) — erst Blocker landen")
+    lines += [
+        "",
+        "Fix (eines):",
+        f"  - re-grill #{issue} → Re-Grill-Reconcile gleicht ab + stempelt plan_revision neu, ODER",
+        "  - bewusster Override in den Handoff-Body:",
+        f"    <!-- guard-ack: #{issue} r<N> reason:<warum> by-user -->",
+        "",
+        "(Legacy-Alt-Anker: <!-- guard-legacy --> in den Anker-Issue setzen (einmalig,",
+        " NICHT in den Handoff) → ganzer Graph grandfathered, kein Block.)",
+    ]
+    return "\n".join(lines)
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception as e:
+        log(HOOK_NAME, f"bad stdin: {e}")
+        return 0
+    try:
+        block, message = should_block(payload)
+    except Exception as e:
+        log(HOOK_NAME, f"should_block crashed: {e} → allow (do not wedge handoff on hook bug)")
+        return 0
+    if not block:
+        return 0
+    print(message, file=sys.stderr)
+    log(HOOK_NAME, f"BLOCKED handoff path={(payload.get('tool_input') or {}).get('file_path')!r}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/hooks/skill-drift-hint.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+SessionStart soft-hint: flag project skills whose declared source files moved in git
+since the skill's own last commit — a cue to re-check the SKILL.md against reality.
+
+Mechanism: each drift-prone skill declares its code/doc anchors in a co-located
+`SOURCES.txt` (one repo-relative path per line; `#` comments and blank lines ignored).
+For each such skill the hook compares `git log -1 --format=%ct` on the SKILL.md vs.
+each source file; a source committed *after* the skill → the skill may be stale.
+
+Committing (touching) the SKILL.md resets the signal — that is how you "quittieren".
+Non-blocking: emits SessionStart additionalContext, silent on every failure.
+
+Carrier is SOURCES.txt (not SKILL.md frontmatter) on purpose: the skill loader's
+tolerance for extra frontmatter keys is unverified, and a sibling file can never
+break skill loading.
+
+Audit log: .claude/logs/skill-drift-hint.log
+"""
+import json
+import sys
+from pathlib import Path
+
+from _hook_utils import log, run, repo_root
+
+HOOK_NAME = "skill-drift-hint"
+SKILLS_REL = ".claude/skills"
+
+
+def git_commit_time(root: str, rel_path: str) -> int | None:
+    """Unix ctime of the last commit touching rel_path; None if untracked/unknown."""
+    out = run(["git", "-C", root, "log", "-1", "--format=%ct", "--", rel_path])
+    return int(out) if out.isdigit() else None
+
+
+def read_sources(sources_file: Path) -> list[str]:
+    """Repo-relative source paths from a SOURCES.txt — skips blanks and `#` comments."""
+    try:
+        lines = sources_file.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return []
+    out: list[str] = []
+    for line in lines:
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        out.append(s)
+    return out
+
+
+def collect_stale(root: str) -> list[tuple[str, list[str]]]:
+    """For each skill with a SOURCES.txt, list sources newer (in git) than its SKILL.md."""
+    skills_dir = Path(root) / SKILLS_REL
+    results: list[tuple[str, list[str]]] = []
+    if not skills_dir.is_dir():
+        return results
+    for sources_file in sorted(skills_dir.glob("*/SOURCES.txt")):
+        skill_name = sources_file.parent.name
+        skill_ct = git_commit_time(root, f"{SKILLS_REL}/{skill_name}/SKILL.md")
+        if skill_ct is None:
+            continue  # skill not committed yet → nothing to compare against
+        stale = [
+            src
+            for src in read_sources(sources_file)
+            if (src_ct := git_commit_time(root, src)) is not None and src_ct > skill_ct
+        ]
+        if stale:
+            results.append((skill_name, stale))
+    return results
+
+
+def build_context(root: str) -> str | None:
+    stale = collect_stale(root)
+    if not stale:
+        return None
+    lines: list[str] = []
+    for skill_name, sources in stale:
+        lines.append(f"⚠ `{skill_name}` — source(s) moved since the skill's last touch:")
+        for src in sources:
+            lines.append(f"    - {src}")
+    block = "\n".join(lines)
+    return (
+        "## Skill freshness (SessionStart hook)\n\n"
+        "```\n"
+        f"{block}\n"
+        "```\n\n"
+        "Heads-up (non-blocking): re-check the named SKILL.md against its source — "
+        "paths/symbols/line numbers may have moved. If the doc still holds, commit the skill "
+        "along with your change (a touch acknowledges the signal). "
+        "Source: .claude/hooks/skill-drift-hint.py + a per-skill SOURCES.txt."
+    )
+
+
+def main() -> int:
+    try:
+        json.load(sys.stdin)
+    except Exception:
+        pass
+
+    root = repo_root() or "."
+    try:
+        context = build_context(root)
+    except Exception as e:
+        log(HOOK_NAME, f"build_context failed: {e}")
+        return 0
+
+    if context is None:
+        return 0
+
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": context,
+        }
+    }
+    print(json.dumps(payload))
+    log(HOOK_NAME, f"emitted: {context.count(chr(0x26A0))} skill(s) flagged")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())