@ikon85/agent-workflow-kit 0.15.0 → 0.16.1

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/logs/drift-guard.log

@@ -0,0 +1,3 @@
+2026-07-15T18:45:54 census state=failed reasons=["target repository unavailable (Command '['git', '-C', '/tmp/repo', 'rev-parse', '--show-toplevel']' returned non-zero exit status 128.)"]
+2026-07-15T18:45:55 census state=failed reasons=['target repository unavailable (handoff target repository containment check failed)']
+2026-07-15T18:45:59 census state=failed reasons=['scan']

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/setup-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-workflow
-description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, GitHub-Projects board field-IDs, spec-self-critique + spec-completeness seeds, workflow overview, and the deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
+description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, board field IDs, spec seeds, workflow overview, optional census choice, and deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
 disable-model-invocation: true
 ---
 
@@ -25,6 +25,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Workflow` in CLAUDE.md **and** AGENTS.md | generic entry-point map seeded from [workflow-overview.md](./workflow-overview.md) (Section F + Write) |
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
+| `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
 
 ## Idempotency contract — read before writing anything
 
@@ -54,6 +55,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CLAUDE.md` and `AGENTS.md` at the repo root — which exist? Do they already have a `## Workflow` / `## Agent skills` / `## Prod` block?
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
+- `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -105,6 +107,34 @@ For GitLab, local, other, or an unknown provider, give only a provider-neutral e
 
 **Conditional board-write note (only when the GitHub tracker uses a managed board):** if Section D ends with `board-sync.md` at `mode: github-projects-v2`, add one line to `issue-tracker.md`: *"Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through the board-sync helper, not bare `gh issue create`/`gh project item-*`."* Do **not** add this for GitLab, local, other, or `mode: none`.
 
+### 2b. Section A3 — Optional project census
+
+> A project census is an optional, consumer-owned map that counts product
+> surfaces and lists behavior families separately. It can make later plans and
+> handoffs more complete, but setup cannot honestly claim coverage before the
+> repository has been scanned and verified.
+
+Read [census.md](./census.md) in full before presenting the choice. If
+`docs/agents/census.md` already records `yes`, `later`, or `no`, adopt that
+choice and do not prompt again on an ordinary setup rerun. Also adopt an
+existing, explicitly documented census path. If no choice exists, ask in plain
+language: *"Should setup prepare the optional project census now?"* Offer
+exactly:
+
+- **Yes** — create or adopt the project layer and minimal enabled profile, run
+  only the shipped self-test, and report the honest `bootstrap` / "not yet
+  meaningful" state. Do not scan, activate, or install a hook or gate.
+- **Later** — record a deferral. Create no census profile, hook, or gate; a
+  later explicit `census-update` invocation may activate without setup.
+- **No** — record the opt-out as `disabled`. Create no census profile, hook, or
+  gate and do not prompt again unless the user explicitly changes the choice.
+
+Use the complete `missing / yes / later / no / existing / explicit-enable /
+disable` matrix in the seed. A later explicit `census-update` invocation may
+activate without rerunning setup. Disable enforcement first, but retain every
+consumer-owned profile, scanner, test, and active snapshot unless the user
+separately approves deletion. Repeated runs are no-ops after reconciliation.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -182,6 +212,14 @@ Seed `docs/agents/code-review.md` from [code-review.md](./code-review.md) — th
 
 For each `docs/...` file: obey the idempotency contract (the "Idempotency contract" section). Prepend the sentinel with the resolved `state` (and `mode` for board-sync).
 
+For `docs/agents/census.md`, seed [census.md](./census.md), prepend the normal
+sentinel, and record the selected choice directly below it as
+`<!-- census: choice=<yes|later|no> -->`. On adoption, also record the discovered
+repository-relative profile and active-snapshot paths. Never overwrite a
+pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
+existing census are terminal for ordinary setup reruns. Only an explicit user
+request changes a recorded choice.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).