@ikon85/agent-workflow-kit 0.16.0 → 0.16.2

package/.agents/skills/kit-update/SKILL.md

@@ -44,6 +44,19 @@ the matching GitHub release contain the same artifact.
    resume the transaction through the update API's `resumeFrom` option. Do not
    copy staged files into the consumer by hand.
 
+5. Check the optional project census after the update:
+
+   ```sh
+   python3 .claude/hooks/drift-guard.py --census-status
+   ```
+
+   When the report names a newer census builder or `refresh_required`, advise
+   the user to run `$census-update`. The kit updater must never overwrite a
+   consumer-owned census, profile, local scanner, decision, or override. A
+   missing, disabled, unactivated, or temporarily unavailable census remains a
+   visible manual-walk condition and does not invalidate an otherwise verified
+   kit update.
+
 ## State contract
 
 The update API reports `checking -> preview/awaiting_decision -> staging ->

package/.agents/skills/to-prd/SKILL.md

@@ -76,6 +76,24 @@ gh project item-list 1 --owner <owner> --limit 500 --format json   # check targe
    - `<!-- prd-source-id: <id> -->` + `<!-- prd-content-fp: <hash> -->` (see step 3).
 5. **Mode B label normalization:** if the reused issue carries wrong/multiple `type:*`, missing `priority:*`, `ready-for-agent`, or `needs-info` → **normalize onto the PRD contract** (exactly one `type:*`, one `priority:*`, no `ready-for-agent`/`needs-info`). Exception per the discriminator (§2): `type:cluster` always, or Wave **without** `wave-stub` → **no** normalization, **hard stop** (step 2); a `wave-stub`-labeled Stufe-1p target normalizes normally — it is a valid Mode B target.
 
+### Census freshness before a cross-cutting lock
+
+When the PRD claims completeness across several product surfaces, run
+`python3 .claude/hooks/drift-guard.py --census-status` before the board write.
+An activated census reporting `refresh_required` means the cross-cutting PRD
+must not be locked: run `$census-update`, resolve every open surface, and retry.
+`disabled`, `no_census`, `bootstrap`, or `offline` stays visible and fail-open;
+perform and report the existing manual walk instead. This gate does not apply
+to an orthogonal, surface-local PRD.
+
+A justified change-local override may acknowledge only a proven mechanical
+false positive. It must carry `scope: "this change"`, a non-empty `reason`, and
+the exact `topologyFingerprint` reported as `change_binding` by the current
+status check. That binding is valid only for those freshly scanned topology
+facts; a later topology change makes the persisted override stale. The
+override never changes scanner facts, builder/topology fingerprints, open
+verdicts, or state resolution, and therefore cannot green real drift.
+
 ## 4b. Program-PRD body (mode=program)
 
 mode=program writes the Program-PRD per `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md` instead of the `<prd-template>` below — a **parallel** grammar for the program altitude, not a replacement (a Feature-PRD keeps using `<prd-template>` unchanged). It carries: the `## Scope` chapter with stable Scope-Item IDs (`S1`, `S2`, …), the machine-parsable `## Wellenplan` table (`Welle | Status | Name | Phase | Slices | Gate | covers`), the `## Phasen-Gates` checklist (only when the program uses phases), the `## Slices` per-slice detail chapter (one `####` section per planned slice, per `SLICE-METADATA-FORMAT.md`'s grammar), and the Abbruch-Konvention. `scripts/program_graph.py` (`board-sync.py validate-graph`) is the parser — to-prd writes the shape, it does not itself validate the graph (that is `to-waves`'s job, run once the Program-PRD exists).

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

@@ -14,17 +14,23 @@ 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).
+first, filename fallback); delegates graph coherence to
+scripts/execute-ready-check.py (`--mode handoff`) and census state/fingerprint
+evaluation to `scripts/census/index.mjs`. Deny = exit 2 + stderr (house pattern:
+enforce-worktree.py, block-secrets.py). A deliberate
+`<!-- guard-ack: #<n> r<N> reason:… by-user -->` overrides only the graph gate,
+never activated census drift. 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 os
 import re
+import stat
+import subprocess
 import sys
 from pathlib import Path
 
@@ -41,11 +47,163 @@ GUARD_ACK_RE = re.compile(r"<!--\s*guard-ack:\s*#?\d+\s+r\d+\s+reason:.+\bby-use
 
 # Load the shared checker (hyphenated filename → importlib). Repo root = parents[2].
 _CHECKER_PATH = Path(__file__).resolve().parents[2] / "scripts" / "execute-ready-check.py"
+_CENSUS_MODULE_PATH = Path(__file__).resolve().parents[2] / "scripts" / "census" / "index.mjs"
+CENSUS_BRIDGE_TIMEOUT_SECONDS = 15
+CENSUS_PROOF_TIMEOUT_MS = 5_000
+
+_CENSUS_SCAN = r"""
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+const input = JSON.parse(readFileSync(0, 'utf8'));
+const {
+  modulePath,
+  repoRoot,
+  profileJson,
+  activeJson,
+  localScanners,
+  profileLocalScanners,
+  localScannersValid,
+  activeLocalScanners,
+  activeLocalScannersValid,
+  proofTimeoutMs,
+} = input;
+const writeResult = process.stdout.write.bind(process.stdout);
+// Repository-local proof modules are allowed to be noisy. Keep their output
+// captured so neither scanner/test output nor accidentally-read content reaches
+// the hook protocol or the CLI status response.
+process.stdout.write = () => true;
+process.stderr.write = () => true;
+const {
+  CENSUS_BUILDER_VERSION,
+  CENSUS_VERDICTS,
+  diffCensus,
+  fingerprintCensus,
+  resolveCensusState,
+  scanCensus,
+} = await import(pathToFileURL(modulePath).href);
+const profile = JSON.parse(profileJson);
+const active = activeJson ? JSON.parse(activeJson) : null;
+const behaviorFamilies = (profile.decisions || []).map(({ family, status }) => ({
+  name: family,
+  status,
+}));
+const fresh = await scanCensus({
+  repoRoot,
+  enabled: Boolean(profile.enabled),
+  hasActive: active !== null,
+  behaviorFamilies,
+});
+const calculated = fingerprintCensus(fresh);
+if (calculated.builder !== fresh.fingerprints.builder
+    || calculated.topology !== fresh.fingerprints.topology) {
+  throw new Error('census fingerprint API returned inconsistent facts');
+}
+const reasons = [];
+const withProofTimeout = async (operation) => {
+  let timer;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('local proof timed out')), proofTimeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+const proofReason = (surface) => typeof surface === 'string' && surface.length > 0
+  ? `proof:${surface}`
+  : 'proof:profile-history';
+if (active !== null) {
+  if (!localScannersValid || !activeLocalScannersValid) {
+    reasons.push('proof:profile-history');
+  } else if (JSON.stringify(profileLocalScanners) !== JSON.stringify(activeLocalScanners)) {
+    const changedSurfaces = new Set([
+      ...profileLocalScanners.map(({ surface }) => surface),
+      ...activeLocalScanners.map(({ surface }) => surface),
+    ]);
+    if (changedSurfaces.size === 0) reasons.push('proof:profile-history');
+    for (const surface of changedSurfaces) reasons.push(proofReason(surface));
+  }
+}
+for (const record of localScanners) {
+  const reason = `proof:${record.surface}`;
+  if (record.validationError) {
+    reasons.push(reason);
+    continue;
+  }
+  const test = spawnSync(process.execPath, ['--test', record.testPath], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: 'pipe',
+    timeout: proofTimeoutMs,
+  });
+  if (test.status !== 0 || test.error) {
+    reasons.push(reason);
+    continue;
+  }
+  try {
+    const scannerModule = await import(`${pathToFileURL(record.modulePath).href}?proof=${Date.now()}`);
+    const scanner = scannerModule[record.exportName];
+    const result = typeof scanner === 'function'
+      ? await withProofTimeout(() => scanner())
+      : null;
+    if (!Array.isArray(result)
+        || !result.every((surface) => typeof surface === 'string')
+        || !result.includes(record.surface)) reasons.push(reason);
+  } catch {
+    reasons.push(reason);
+  }
+}
+if (active !== null && active.fingerprints?.builder !== fresh.fingerprints.builder) reasons.push('builder');
+if (active !== null && active.fingerprints?.topology !== fresh.fingerprints.topology) reasons.push('topology');
+const uniqueReasons = [...new Set(reasons)];
+const hasOpen = uniqueReasons.some((reason) => reason.startsWith('proof:'))
+  || [...fresh.families.surfaces, ...fresh.families.behaviors]
+    .some(({ status }) => status === CENSUS_VERDICTS.open);
+if (hasOpen) uniqueReasons.push('open');
+const delta = active === null ? null : diffCensus(active, fresh);
+const denominatorUnchanged = delta !== null
+  && Object.values(delta).every((paths) => paths.length === 0);
+const familiesUnchanged = active !== null
+  && JSON.stringify(active.families) === JSON.stringify(fresh.families);
+const mechanicalFalsePositive = uniqueReasons.length === 1
+  && uniqueReasons[0] === 'topology'
+  && denominatorUnchanged
+  && familiesUnchanged;
+const state = resolveCensusState({
+  enabled: Boolean(profile.enabled),
+  hasActive: active !== null,
+  hasOpen: hasOpen || uniqueReasons.includes('builder') || uniqueReasons.includes('topology'),
+});
+writeResult(JSON.stringify({
+  builderVersion: CENSUS_BUILDER_VERSION,
+  changeBinding: fresh.fingerprints.topology,
+  fresh: {
+    ...fresh,
+    profileReport: {
+      decisions: profile.decisions || [],
+      localScanners: profile.localScanners,
+      overrides: profile.overrides || [],
+    },
+    state,
+  },
+  mechanicalFalsePositive,
+  reasons: uniqueReasons,
+  state,
+}));
+"""
 
 
 _CHECKER = None
 
 
+class CensusFileError(Exception):
+    """A census control file failed the contained-regular-file contract."""
+
+
 def _load_checker():
     """Load + cache the shared checker (module exec is not free — load once per
     process, not once per call site)."""
@@ -65,6 +223,135 @@ def is_handoff_write(payload: dict) -> bool:
     return bool(HANDOFF_PATH_RE.search(fp))
 
 
+def _git_root(start: Path) -> Path:
+    """Resolve the owning repository without treating process cwd as ownership."""
+    completed = subprocess.run(
+        ["git", "-C", str(start), "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        check=True,
+        text=True,
+        timeout=5,
+    )
+    return Path(completed.stdout.strip()).resolve()
+
+
+def resolve_census_root_from_cwd(cwd: Path) -> Path:
+    """CLI entry points may be invoked from any directory inside the repo."""
+    return _git_root(cwd.resolve())
+
+
+def resolve_handoff_repo_root(payload: dict) -> Path:
+    """Return the repository that owns the handoff target.
+
+    The raw target identifies the claimed repository, while the resolved target
+    proves that `.handoff` did not escape it through a symlink. This permits a
+    hook launched from another checkout without trusting an arbitrary payload
+    path as the census root.
+    """
+    raw = (payload.get("tool_input") or {}).get("file_path", "")
+    if not raw:
+        raise ValueError("missing handoff target repository path")
+    target = Path(raw)
+    if not target.is_absolute():
+        target = Path(os.path.abspath(Path.cwd() / target))
+    else:
+        target = Path(os.path.abspath(target))
+    if target.parent.name != ".handoff":
+        raise ValueError("handoff target is not rooted in a target repository .handoff directory")
+    claimed_root = _git_root(target.parent.parent)
+    expected_handoff = claimed_root / ".handoff"
+    if target.parent != expected_handoff:
+        raise ValueError("handoff target repository does not own the claimed .handoff path")
+    resolved_target = target.resolve(strict=False)
+    try:
+        relative = resolved_target.relative_to(claimed_root)
+    except ValueError as error:
+        raise ValueError("handoff target repository containment check failed") from error
+    if not relative.parts or relative.parts[0] != ".handoff":
+        raise ValueError("handoff target repository containment check failed")
+    return claimed_root
+
+
+def _path_entry_exists(path: Path) -> bool:
+    """Unlike exists(), count dangling symlinks as present activation state."""
+    try:
+        path.lstat()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _contained_regular_file(repo_root: Path, local_path) -> Path | None:
+    """Resolve a readable repo-local regular file without following a final link."""
+    if not isinstance(local_path, str) or not local_path or Path(local_path).is_absolute():
+        return None
+    lexical_root = Path(os.path.abspath(repo_root))
+    candidate = Path(os.path.abspath(lexical_root / local_path))
+    try:
+        candidate.relative_to(lexical_root)
+    except ValueError:
+        return None
+    try:
+        info = candidate.lstat()
+        if not stat.S_ISREG(info.st_mode) or stat.S_ISLNK(info.st_mode):
+            return None
+        if not info.st_mode & (stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH):
+            return None
+        canonical_root = lexical_root.resolve(strict=True)
+        canonical = candidate.resolve(strict=True)
+        canonical.relative_to(canonical_root)
+    except (FileNotFoundError, OSError, RuntimeError, ValueError):
+        return None
+    return candidate
+
+
+def _read_census_control(repo_root: Path, local_path: str) -> str:
+    target = _contained_regular_file(repo_root, local_path)
+    if target is None:
+        raise CensusFileError(f"invalid {Path(local_path).name}")
+    try:
+        return target.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        raise CensusFileError(f"unreadable {Path(local_path).name}") from error
+
+
+def _normalize_local_scanners(records) -> tuple[bool, list[dict]]:
+    """Return the exact proof-record contract without trusting arbitrary JSON shapes."""
+    if not isinstance(records, list):
+        return False, []
+    normalized = []
+    for raw in records:
+        if not isinstance(raw, dict):
+            return False, normalized
+        record = {}
+        for key in ("surface", "module", "export", "test"):
+            value = raw.get(key)
+            if not isinstance(value, str) or not value.strip():
+                return False, normalized
+            record[key] = value.strip()
+        normalized.append(record)
+    return True, normalized
+
+
+def _validated_local_scanners(repo_root: Path, records: list[dict]) -> list[dict]:
+    """Convert profile records to proof inputs without exposing unsafe paths."""
+    validated = []
+    for raw in records:
+        surface = raw["surface"]
+        module_path = _contained_regular_file(repo_root, raw.get("module"))
+        test_path = _contained_regular_file(repo_root, raw.get("test"))
+        export_name = raw.get("export")
+        valid_export = isinstance(export_name, str) and bool(export_name.strip())
+        validated.append({
+            "surface": surface,
+            "modulePath": str(module_path) if module_path else "",
+            "testPath": str(test_path) if test_path else "",
+            "exportName": export_name.strip() if valid_export else "",
+            "validationError": not (module_path and test_path and valid_export),
+        })
+    return validated
+
+
 def extract_content(payload: dict) -> str:
     ti = payload.get("tool_input") or {}
     tool = payload.get("tool_name")
@@ -97,7 +384,7 @@ def run_check(issue: int, intent: str) -> dict:
     try:
         checker = _load_checker()
         return checker.build_and_evaluate(issue, "handoff", intent)
-    except Exception as e:
+    except (Exception, SystemExit) 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,
@@ -108,23 +395,186 @@ def run_check(issue: int, intent: str) -> dict:
 def _infer_intent(content: str) -> str:
     try:
         return _load_checker().infer_intent(content)
-    except Exception:
+    except (Exception, SystemExit):
         return "build"
 
 
+def scan_census_status(repo_root: Path, profile_json=None, active_json=None,
+                       proof_timeout_ms=CENSUS_PROOF_TIMEOUT_MS) -> dict:
+    """Scan census facts through the shipped JavaScript API, never a hook-local
+    copy of its state or fingerprint rules."""
+    active_path = repo_root / ".census" / "active.json"
+    profile = profile_json if profile_json is not None else _read_census_control(
+        repo_root, ".census/profile.json"
+    )
+    active = active_json
+    if active is None:
+        active = _read_census_control(repo_root, ".census/active.json") \
+            if _path_entry_exists(active_path) else ""
+    try:
+        profile_body = json.loads(profile)
+    except (json.JSONDecodeError, TypeError) as error:
+        raise CensusFileError("invalid profile.json") from error
+    if not isinstance(profile_body, dict):
+        raise CensusFileError("invalid profile.json")
+    if not isinstance(proof_timeout_ms, int) or isinstance(proof_timeout_ms, bool):
+        raise ValueError("proof timeout must be an integer")
+    proof_timeout_ms = max(1, min(
+        proof_timeout_ms,
+        CENSUS_BRIDGE_TIMEOUT_SECONDS * 1_000 - 1,
+    ))
+    profile_scanners_valid, profile_scanners = _normalize_local_scanners(
+        profile_body.get("localScanners")
+    )
+    active_scanners_valid = True
+    active_scanners = []
+    if active:
+        try:
+            active_body = json.loads(active)
+            report = active_body.get("profileReport") if isinstance(active_body, dict) else None
+            active_scanners_valid, active_scanners = _normalize_local_scanners(
+                report.get("localScanners") if isinstance(report, dict) else None
+            )
+        except (json.JSONDecodeError, TypeError):
+            active_scanners_valid = False
+    # Each record has two independently bounded proof phases (test + scanner).
+    # Keep their aggregate ceiling below the outer bridge budget as well as
+    # making every inner timeout strictly smaller than it.
+    proof_timeout_ms = min(
+        proof_timeout_ms,
+        max(1, (CENSUS_BRIDGE_TIMEOUT_SECONDS * 1_000 - 2_000)
+            // max(1, len(profile_scanners) * 2)),
+    )
+    completed = subprocess.run(
+        ["node", "--input-type=module", "-e", _CENSUS_SCAN],
+        capture_output=True,
+        check=True,
+        input=json.dumps({
+            "modulePath": str(_CENSUS_MODULE_PATH),
+            "repoRoot": str(repo_root),
+            "profileJson": profile,
+            "activeJson": active,
+            "localScanners": _validated_local_scanners(repo_root, profile_scanners),
+            "profileLocalScanners": profile_scanners,
+            "localScannersValid": profile_scanners_valid,
+            "activeLocalScanners": active_scanners,
+            "activeLocalScannersValid": active_scanners_valid,
+            "proofTimeoutMs": proof_timeout_ms,
+        }),
+        text=True,
+        timeout=CENSUS_BRIDGE_TIMEOUT_SECONDS,
+    )
+    return json.loads(completed.stdout)
+
+
+def evaluate_census(repo_root: Path, proof_timeout_ms=CENSUS_PROOF_TIMEOUT_MS) -> dict:
+    """Return the activation-aware handoff verdict.
+
+    Missing/disabled/unactivated/unavailable census remains visible but does not
+    gate ordinary work. Only an explicitly enabled, activated census may fail
+    closed. Consumer overrides are reported and deliberately never fed into
+    scanning, fingerprinting, or state resolution.
+    """
+    profile_path = repo_root / ".census" / "profile.json"
+    active_path = repo_root / ".census" / "active.json"
+    profile_present = _path_entry_exists(profile_path)
+    active_present = _path_entry_exists(active_path)
+    if not profile_present:
+        if active_present:
+            return {"state": "failed", "block_handoff": False,
+                    "detail": "active census has no valid profile",
+                    "reasons": ["profile"], "overrides": [], "override_applied": False}
+        return {"state": "no_census", "block_handoff": False, "detail": "manual walk required",
+                "reasons": [], "overrides": [], "override_applied": False}
+    try:
+        profile_json = _read_census_control(repo_root, ".census/profile.json")
+        profile = json.loads(profile_json)
+        if not isinstance(profile, dict):
+            raise ValueError("profile must be an object")
+    except (CensusFileError, json.JSONDecodeError, ValueError, TypeError):
+        return {"state": "failed", "block_handoff": False,
+                "detail": "census profile is invalid or unreadable",
+                "reasons": ["profile"], "overrides": [], "override_applied": False}
+    try:
+        active_json = _read_census_control(repo_root, ".census/active.json") \
+            if active_present else ""
+        result = scan_census_status(repo_root, profile_json, active_json, proof_timeout_ms)
+    except (OSError, subprocess.TimeoutExpired) as error:
+        activated = active_present and bool(profile.get("enabled"))
+        return {"state": "offline", "block_handoff": activated, "detail": str(error),
+                "reasons": [], "overrides": profile.get("overrides", []), "override_applied": False}
+    except Exception:
+        activated = active_present and bool(profile.get("enabled"))
+        return {"state": "failed", "block_handoff": activated,
+                "detail": "census scan or active snapshot is invalid",
+                "reasons": ["scan"], "overrides": profile.get("overrides", []),
+                "override_applied": False}
+    state = result["state"]
+    activated = active_present
+    overrides = profile.get("overrides", [])
+    change_binding = result["changeBinding"]
+    justified_change_local = any(
+        override.get("scope") == "this change"
+        and isinstance(override.get("reason"), str)
+        and bool(override.get("reason").strip())
+        and override.get("topologyFingerprint") == change_binding
+        for override in overrides
+        if isinstance(override, dict)
+    )
+    override_applied = result["mechanicalFalsePositive"] and justified_change_local
+    return {
+        "state": state,
+        "block_handoff": activated and state == "refresh_required" and not override_applied,
+        "detail": f"builder {result['builderVersion']}",
+        "reasons": result["reasons"],
+        "overrides": overrides,
+        "override_applied": override_applied,
+        "change_binding": result["changeBinding"],
+        "mechanical_false_positive": result["mechanicalFalsePositive"],
+    }
+
+
+def build_census_block_message(issue: int, result: dict) -> str:
+    reasons = ", ".join(result.get("reasons", [])) or "activated census is stale"
+    lines = [
+        f"CENSUS — Build-Handoff für #{issue} BLOCKED ({result.get('state', 'refresh_required')}):",
+        "",
+        f"  · {reasons}",
+        "  · run `$census-update` and activate a verified current census",
+    ]
+    if result.get("overrides"):
+        lines += [
+            "  · change-local overrides remain visible but cannot green real drift",
+        ]
+    return "\n".join(lines)
+
+
 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)
+    try:
+        census_root = resolve_handoff_repo_root(payload)
+        census = evaluate_census(census_root)
+    except Exception as error:
+        census = {
+            "state": "failed",
+            "block_handoff": intent == "build",
+            "reasons": [f"target repository unavailable ({error})"],
+            "overrides": [],
+        }
+    log(HOOK_NAME, f"census state={census['state']} reasons={census.get('reasons', [])}")
+    if intent == "build" and census.get("block_handoff"):
+        return True, build_census_block_message(issue, census)
+    if GUARD_ACK_RE.search(content):
+        log(HOOK_NAME, "guard-ack override present → allow graph gate only")
+        return False, ""
     result = run_check(issue, intent)
     if result.get("deny_recommended"):
         return True, build_block_message(issue, intent, result)
@@ -155,6 +605,17 @@ def build_block_message(issue: int, intent: str, result: dict) -> str:
 
 
 def main() -> int:
+    if sys.argv[1:] == ["--census-status"]:
+        try:
+            root = resolve_census_root_from_cwd(Path.cwd())
+            result = evaluate_census(root)
+        except Exception as error:
+            result = {"state": "failed", "block_handoff": False,
+                      "detail": f"target repository unavailable ({error})",
+                      "reasons": ["repository"], "overrides": [],
+                      "override_applied": False}
+        print(json.dumps(result, sort_keys=True))
+        return 0
     try:
         payload = json.load(sys.stdin)
     except Exception as e:

package/.claude/skills/kit-update/SKILL.md

@@ -44,6 +44,19 @@ the matching GitHub release contain the same artifact.
    resume the transaction through the update API's `resumeFrom` option. Do not
    copy staged files into the consumer by hand.
 
+5. Check the optional project census after the update:
+
+   ```sh
+   python3 .claude/hooks/drift-guard.py --census-status
+   ```
+
+   When the report names a newer census builder or `refresh_required`, advise
+   the user to run `$census-update`. The kit updater must never overwrite a
+   consumer-owned census, profile, local scanner, decision, or override. A
+   missing, disabled, unactivated, or temporarily unavailable census remains a
+   visible manual-walk condition and does not invalidate an otherwise verified
+   kit update.
+
 ## State contract
 
 The update API reports `checking -> preview/awaiting_decision -> staging ->

package/.claude/skills/to-prd/SKILL.md

@@ -76,6 +76,24 @@ gh project item-list 1 --owner <owner> --limit 500 --format json   # check targe
    - `<!-- prd-source-id: <id> -->` + `<!-- prd-content-fp: <hash> -->` (see step 3).
 5. **Mode B label normalization:** if the reused issue carries wrong/multiple `type:*`, missing `priority:*`, `ready-for-agent`, or `needs-info` → **normalize onto the PRD contract** (exactly one `type:*`, one `priority:*`, no `ready-for-agent`/`needs-info`). Exception per the discriminator (§2): `type:cluster` always, or Wave **without** `wave-stub` → **no** normalization, **hard stop** (step 2); a `wave-stub`-labeled Stufe-1p target normalizes normally — it is a valid Mode B target.
 
+### Census freshness before a cross-cutting lock
+
+When the PRD claims completeness across several product surfaces, run
+`python3 .claude/hooks/drift-guard.py --census-status` before the board write.
+An activated census reporting `refresh_required` means the cross-cutting PRD
+must not be locked: run `$census-update`, resolve every open surface, and retry.
+`disabled`, `no_census`, `bootstrap`, or `offline` stays visible and fail-open;
+perform and report the existing manual walk instead. This gate does not apply
+to an orthogonal, surface-local PRD.
+
+A justified change-local override may acknowledge only a proven mechanical
+false positive. It must carry `scope: "this change"`, a non-empty `reason`, and
+the exact `topologyFingerprint` reported as `change_binding` by the current
+status check. That binding is valid only for those freshly scanned topology
+facts; a later topology change makes the persisted override stale. The
+override never changes scanner facts, builder/topology fingerprints, open
+verdicts, or state resolution, and therefore cannot green real drift.
+
 ## 4b. Program-PRD body (mode=program)
 
 mode=program writes the Program-PRD per `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md` instead of the `<prd-template>` below — a **parallel** grammar for the program altitude, not a replacement (a Feature-PRD keeps using `<prd-template>` unchanged). It carries: the `## Scope` chapter with stable Scope-Item IDs (`S1`, `S2`, …), the machine-parsable `## Wellenplan` table (`Welle | Status | Name | Phase | Slices | Gate | covers`), the `## Phasen-Gates` checklist (only when the program uses phases), the `## Slices` per-slice detail chapter (one `####` section per planned slice, per `SLICE-METADATA-FORMAT.md`'s grammar), and the Abbruch-Konvention. `scripts/program_graph.py` (`board-sync.py validate-graph`) is the parser — to-prd writes the shape, it does not itself validate the graph (that is `to-waves`'s job, run once the Program-PRD exists).

package/README.md

@@ -332,6 +332,18 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.16.2
+
+- Metadata-only release.
+
+### 0.16.1
+
+- changed: `.agents/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/to-prd/SKILL.md`
+- changed: `.claude/hooks/drift-guard.py`
+- changed: `.claude/skills/kit-update/SKILL.md`
+- changed: `.claude/skills/to-prd/SKILL.md`
+
 ### 0.16.0
 
 - added: `.agents/skills/setup-workflow/census.md`