@ikon85/agent-workflow-kit 0.14.0 → 0.15.0

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

@@ -0,0 +1,140 @@
+---
+name: census-update
+description: "Build, refresh, or check an optional project-local census. Use when a user invokes census-update, asks to establish a counted surface census, or needs to reconcile census drift; scan facts in the current repository, guide only ambiguous decisions, and activate a verified candidate transactionally."
+---
+
+# Census Update
+
+Build and maintain the current repository's consumer-owned census through the
+public API in `scripts/census/index.mjs`. Keep this skill a thin coordinator:
+do not copy, rename, or reimplement the scanner, state, delta, fingerprint, or
+transaction logic.
+
+## Boundaries
+
+- Work only in the current repository. Never inspect another project, aggregate
+  cross-project findings, learn shared recipes from other repositories, or
+  propose an upstream kit change.
+- Treat code as the source of facts. Never ask the user which files, paths, or
+  patterns exist.
+- Ask only for one genuinely ambiguous decision at a time. Include a concise
+  recommendation and the evidence behind it.
+- Keep generated scanners, tests, profiles, decisions, and the active census in
+  the consumer repository. Do not add a dependency without explicit approval.
+
+## Public mechanism
+
+Import only the stable exports from `scripts/census/index.mjs`:
+`scanCensus`, `serializeCensus`, `fingerprintCensus`,
+`CENSUS_BUILDER_VERSION`, `diffCensus`, `CENSUS_STATES`, `CENSUS_VERDICTS`,
+`resolveCensusState`, `activateCensus`, and `CensusTransactionError`.
+
+## Consumer files
+
+First adopt an existing, explicitly documented census path convention when the
+repository has one. Otherwise use `.census/profile.json` for the consumer-owned
+profile and `.census/active.json` for the verified snapshot. A missing default
+profile is not an error: report `bootstrap` and stage it only after facts and
+decisions are ready rather than silently enabling a gate.
+
+The deterministic profile schema is:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "decisions": [
+    { "family": "name", "status": "verdict", "evidence": "fact", "justification": "required when not relevant" }
+  ],
+  "localScanners": [
+    { "surface": "family", "module": "repo-relative path", "export": "function", "test": "repo-relative test path" }
+  ],
+  "overrides": [
+    { "scope": "this change", "reason": "visible display-only reason" }
+  ]
+}
+```
+
+Keep all three arrays present and order their records by family or surface, then
+path. Preserve extra consumer-owned keys when rewriting an adopted profile.
+Pass `decisions` to `scanCensus` as `behaviorFamilies` after mapping `family` to
+`name`. Put the unchanged decision, local-scanner, and override records in a
+visible `profileReport` beside the scanned snapshot. Derive snapshot state with
+`resolveCensusState`; never assign `current` as a literal shortcut.
+
+Local-scanner records configure the verifier passed to `activateCensus`: run
+the named focused test, import the named repository-local export, and require
+its result to include the recorded surface. Both `module` and `test` must be
+repository-relative, contained regular files; reject absolute paths, `..`
+escapes, and symlinks before executing or importing either one. Compare surface
+families with the previous active snapshot; a new family without that passing
+proof is still open for state resolution even when Git tracking lets the base
+scan enumerate it. Overrides are report input only and are never passed into
+scanning, fingerprinting, verification, or state resolution.
+
+## Workflow
+
+1. **Check.** Read the local profile and active census, if present. Report a
+   missing profile as `bootstrap`; otherwise derive one
+   of `disabled`, `bootstrap`, `current`, `refresh_required`, `updating`, or
+   `failed` through the public API. An explicit opt-out is disabled. Do not
+   write during this step.
+2. **Scan facts.** Call `scanCensus` once with the current repository root.
+   Product code and production configuration form the surface denominator;
+   tests and docs remain evidence. Let the scanner exclude secrets, ignored,
+   generated, and vendored content. Never read excluded content to explain a
+   result.
+3. **Show the delta.** For an active census, call `diffCensus` and show only
+   added, changed, removed, and open names. Do not dump the full scan unless the
+   user asks. For bootstrap, show the discovered families and counts.
+4. **Resolve ambiguity.** Recommend a decision for each ambiguous behavior or
+   surface and ask separately. Record the user's decision with its evidence.
+   `nicht relevant` requires a durable justification. Never infer it silently. <!-- language-census: ok -->
+5. **Handle unknown patterns locally.** Keep an unknown surface `offen`. It can
+   become `abgedeckt` only after this repository contains a small local scanner
+   and a focused passing test for that pattern. Run that test before rescanning.
+6. **Verify a candidate.** Build the candidate from the fresh scan and recorded
+   decisions. Fail verification when any surface or behavior remains `offen`,
+   when a required local scanner test fails, or when the candidate fingerprints
+   do not describe the current repository.
+7. **Activate.** Call `activateCensus` with a real verifier so it stages, verifies,
+   and atomically swaps under its local lock. On `CensusTransactionError`, report
+   `updating` or `failed` and keep the previous active census authoritative.
+8. **Prove the result.** Report surface coverage as `X of Y`, then render the
+   behavior overview separately. State the resulting census state and the
+   builder version.
+
+## Decision rules
+
+- Store a justified `nicht relevant` verdict as a visible decision beside the <!-- language-census: ok -->
+  candidate; do not erase the family from the overview.
+- A change-local override may suppress a known mechanical false-positive in
+  the displayed delta only when its reason and scope are visible. It must not
+  alter scanner facts, fingerprints, `offen` verdicts, or state resolution, so
+  real drift can never become `current` through an override.
+- Any unexpected product area stays `offen` and therefore prevents `current`,
+  even if every known area is covered.
+- Facts discovered after a decision invalidate that decision's stale premise;
+  rescan and ask again only if the remaining choice is genuinely ambiguous.
+
+## No-write and recovery proof
+
+Before activation, compare the fresh candidate with the active census using
+the public fingerprints and deterministic `serializeCensus` output. If the
+repository and decisions are unchanged and the derived state is `current`,
+report `current` and do not call `activateCensus` or write any file.
+
+If scanning, a local test, verification, or activation fails, report `failed`,
+discard the candidate when safe, and confirm that the previous active census
+bytes are unchanged. Never manufacture `current` after an error.
+
+## Final report
+
+Return only the useful audit trail:
+
+- state and builder version;
+- compact delta;
+- surface coverage `X of Y`;
+- separate behavior overview;
+- visible `nicht relevant` justifications and active override, if any; <!-- language-census: ok -->
+- local scanner tests run and the transaction/no-write result.

package/.agents/skills/setup-workflow/workflow-overview.md

@@ -17,6 +17,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **A design question needs a runnable answer (state, business logic, a UI you have to see):** spike it with `prototype`, then fold what you learned back in.
 - **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
+- **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.

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

@@ -0,0 +1,140 @@
+---
+name: census-update
+description: "Build, refresh, or check an optional project-local census. Use when a user invokes census-update, asks to establish a counted surface census, or needs to reconcile census drift; scan facts in the current repository, guide only ambiguous decisions, and activate a verified candidate transactionally."
+---
+
+# Census Update
+
+Build and maintain the current repository's consumer-owned census through the
+public API in `scripts/census/index.mjs`. Keep this skill a thin coordinator:
+do not copy, rename, or reimplement the scanner, state, delta, fingerprint, or
+transaction logic.
+
+## Boundaries
+
+- Work only in the current repository. Never inspect another project, aggregate
+  cross-project findings, learn shared recipes from other repositories, or
+  propose an upstream kit change.
+- Treat code as the source of facts. Never ask the user which files, paths, or
+  patterns exist.
+- Ask only for one genuinely ambiguous decision at a time. Include a concise
+  recommendation and the evidence behind it.
+- Keep generated scanners, tests, profiles, decisions, and the active census in
+  the consumer repository. Do not add a dependency without explicit approval.
+
+## Public mechanism
+
+Import only the stable exports from `scripts/census/index.mjs`:
+`scanCensus`, `serializeCensus`, `fingerprintCensus`,
+`CENSUS_BUILDER_VERSION`, `diffCensus`, `CENSUS_STATES`, `CENSUS_VERDICTS`,
+`resolveCensusState`, `activateCensus`, and `CensusTransactionError`.
+
+## Consumer files
+
+First adopt an existing, explicitly documented census path convention when the
+repository has one. Otherwise use `.census/profile.json` for the consumer-owned
+profile and `.census/active.json` for the verified snapshot. A missing default
+profile is not an error: report `bootstrap` and stage it only after facts and
+decisions are ready rather than silently enabling a gate.
+
+The deterministic profile schema is:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "decisions": [
+    { "family": "name", "status": "verdict", "evidence": "fact", "justification": "required when not relevant" }
+  ],
+  "localScanners": [
+    { "surface": "family", "module": "repo-relative path", "export": "function", "test": "repo-relative test path" }
+  ],
+  "overrides": [
+    { "scope": "this change", "reason": "visible display-only reason" }
+  ]
+}
+```
+
+Keep all three arrays present and order their records by family or surface, then
+path. Preserve extra consumer-owned keys when rewriting an adopted profile.
+Pass `decisions` to `scanCensus` as `behaviorFamilies` after mapping `family` to
+`name`. Put the unchanged decision, local-scanner, and override records in a
+visible `profileReport` beside the scanned snapshot. Derive snapshot state with
+`resolveCensusState`; never assign `current` as a literal shortcut.
+
+Local-scanner records configure the verifier passed to `activateCensus`: run
+the named focused test, import the named repository-local export, and require
+its result to include the recorded surface. Both `module` and `test` must be
+repository-relative, contained regular files; reject absolute paths, `..`
+escapes, and symlinks before executing or importing either one. Compare surface
+families with the previous active snapshot; a new family without that passing
+proof is still open for state resolution even when Git tracking lets the base
+scan enumerate it. Overrides are report input only and are never passed into
+scanning, fingerprinting, verification, or state resolution.
+
+## Workflow
+
+1. **Check.** Read the local profile and active census, if present. Report a
+   missing profile as `bootstrap`; otherwise derive one
+   of `disabled`, `bootstrap`, `current`, `refresh_required`, `updating`, or
+   `failed` through the public API. An explicit opt-out is disabled. Do not
+   write during this step.
+2. **Scan facts.** Call `scanCensus` once with the current repository root.
+   Product code and production configuration form the surface denominator;
+   tests and docs remain evidence. Let the scanner exclude secrets, ignored,
+   generated, and vendored content. Never read excluded content to explain a
+   result.
+3. **Show the delta.** For an active census, call `diffCensus` and show only
+   added, changed, removed, and open names. Do not dump the full scan unless the
+   user asks. For bootstrap, show the discovered families and counts.
+4. **Resolve ambiguity.** Recommend a decision for each ambiguous behavior or
+   surface and ask separately. Record the user's decision with its evidence.
+   `nicht relevant` requires a durable justification. Never infer it silently. <!-- language-census: ok -->
+5. **Handle unknown patterns locally.** Keep an unknown surface `offen`. It can
+   become `abgedeckt` only after this repository contains a small local scanner
+   and a focused passing test for that pattern. Run that test before rescanning.
+6. **Verify a candidate.** Build the candidate from the fresh scan and recorded
+   decisions. Fail verification when any surface or behavior remains `offen`,
+   when a required local scanner test fails, or when the candidate fingerprints
+   do not describe the current repository.
+7. **Activate.** Call `activateCensus` with a real verifier so it stages, verifies,
+   and atomically swaps under its local lock. On `CensusTransactionError`, report
+   `updating` or `failed` and keep the previous active census authoritative.
+8. **Prove the result.** Report surface coverage as `X of Y`, then render the
+   behavior overview separately. State the resulting census state and the
+   builder version.
+
+## Decision rules
+
+- Store a justified `nicht relevant` verdict as a visible decision beside the <!-- language-census: ok -->
+  candidate; do not erase the family from the overview.
+- A change-local override may suppress a known mechanical false-positive in
+  the displayed delta only when its reason and scope are visible. It must not
+  alter scanner facts, fingerprints, `offen` verdicts, or state resolution, so
+  real drift can never become `current` through an override.
+- Any unexpected product area stays `offen` and therefore prevents `current`,
+  even if every known area is covered.
+- Facts discovered after a decision invalidate that decision's stale premise;
+  rescan and ask again only if the remaining choice is genuinely ambiguous.
+
+## No-write and recovery proof
+
+Before activation, compare the fresh candidate with the active census using
+the public fingerprints and deterministic `serializeCensus` output. If the
+repository and decisions are unchanged and the derived state is `current`,
+report `current` and do not call `activateCensus` or write any file.
+
+If scanning, a local test, verification, or activation fails, report `failed`,
+discard the candidate when safe, and confirm that the previous active census
+bytes are unchanged. Never manufacture `current` after an error.
+
+## Final report
+
+Return only the useful audit trail:
+
+- state and builder version;
+- compact delta;
+- surface coverage `X of Y`;
+- separate behavior overview;
+- visible `nicht relevant` justifications and active override, if any; <!-- language-census: ok -->
+- local scanner tests run and the transaction/no-write result.

package/.claude/skills/setup-workflow/workflow-overview.md

@@ -17,6 +17,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **A design question needs a runnable answer (state, business logic, a UI you have to see):** spike it with `prototype`, then fold what you learned back in.
 - **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
+- **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.

package/.claude/skills/skill-manifest.json

@@ -107,6 +107,16 @@
       ],
       "provenance": "matt-pocock"
     },
+    "census-update": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
     "board-to-waves": {
       "class": "generic",
       "publish": true,

package/PROVENANCE.md

@@ -32,8 +32,8 @@ carries Chase's `THIRD-PARTY-NOTICES.md`.
 ## Own work (MIT, Copyright (c) 2026 Niko (iKon85))
 
 retro, wrapup, spec-self-critique, board-to-waves, verify-spike, decision-gate,
-codex-adapter-sync, setup-pre-commit, code-review, orchestrate-wave — covered by
-the root LICENSE.
+codex-adapter-sync, setup-pre-commit, code-review, orchestrate-wave,
+census-update — covered by the root LICENSE.
 `setup-pre-commit` was rewritten from Matt Pocock's husky-based skill to a
 zero-dep native git `core.hooksPath` scaffold; nothing of the original
 mechanic remains (courtesy attribution).

package/README.md

@@ -332,6 +332,13 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.15.0
+
+- added: `.agents/skills/census-update/SKILL.md`
+- added: `.claude/skills/census-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
 ### 0.14.0
 
 - added: `scripts/census/delta.mjs`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.14.0",
+  "kitVersion": "0.15.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -37,6 +37,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/census-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "census-update",
+      "surface": "codex",
+      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/code-review/SKILL.md",
       "kind": "skill",
@@ -582,7 +591,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
+      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
       "mode": 420,
       "origin": "kit"
     },
@@ -893,6 +902,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/census-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "census-update",
+      "surface": "claude",
+      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/code-review/SKILL.md",
       "kind": "skill",
@@ -1564,7 +1582,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
+      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/test_census_update_contract.test.mjs

@@ -0,0 +1,440 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { access, lstat, mkdtemp, mkdir, readFile, realpath, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  CENSUS_VERDICTS,
+  activateCensus,
+  diffCensus,
+  fingerprintCensus,
+  resolveCensusState,
+  scanCensus,
+  serializeCensus,
+} from './census/index.mjs';
+
+const ROOT = new URL('../', import.meta.url);
+const exec = promisify(execFile);
+
+async function text(path) {
+  return readFile(new URL(path, ROOT), 'utf8');
+}
+
+async function makeBrownfield() {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-update-'));
+  await mkdir(join(root, 'apps/api/src'), { recursive: true });
+  await mkdir(join(root, 'apps/web/src'), { recursive: true });
+  await writeFile(join(root, 'package.json'), '{"name":"brownfield","type":"module"}\n');
+  await writeFile(join(root, 'apps/api/src/index.mjs'), 'export const api = true;\n');
+  await writeFile(join(root, 'apps/web/src/index.mjs'), 'export const web = true;\n');
+  await exec('git', ['init', '--quiet'], { cwd: root });
+  await exec('git', ['add', '.'], { cwd: root });
+  return root;
+}
+
+const PROFILE_RELATIVE_PATH = '.census/profile.json';
+const ACTIVE_RELATIVE_PATH = '.census/active.json';
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+function profileBehaviorFamilies(profile) {
+  return profile.decisions.map(({ family, status }) => ({ name: family, status }));
+}
+
+async function containedRegularPath(root, localPath) {
+  if (typeof localPath !== 'string' || !localPath || isAbsolute(localPath)) return null;
+  const target = resolve(root, localPath);
+  const lexical = relative(resolve(root), target);
+  if (lexical === '..' || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) return null;
+  const stats = await lstat(target);
+  if (!stats.isFile() || stats.isSymbolicLink()) return null;
+  const canonicalRoot = await realpath(root);
+  const canonical = await realpath(target);
+  const canonicalRelative = relative(canonicalRoot, canonical);
+  if (canonicalRelative === '..' || canonicalRelative.startsWith(`..${sep}`)
+    || isAbsolute(canonicalRelative)) return null;
+  return target;
+}
+
+async function runLocalScannerProof(root, record) {
+  const modulePath = await containedRegularPath(root, record.module);
+  const testPath = await containedRegularPath(root, record.test);
+  if (!modulePath || !testPath) return false;
+  await exec('node', ['--test', record.test], { cwd: root });
+  const scanner = await import(`${pathToFileURL(modulePath).href}?proof=${Date.now()}`);
+  return scanner[record.export]().includes(record.surface);
+}
+
+async function runConsumerCensus(root) {
+  const profilePath = join(root, PROFILE_RELATIVE_PATH);
+  const activePath = join(root, ACTIVE_RELATIVE_PATH);
+  const profile = await readJson(profilePath);
+  let previous = null;
+  try {
+    previous = await readJson(activePath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const scan = await scanCensus({
+    repoRoot: root,
+    enabled: profile.enabled,
+    hasActive: previous !== null,
+    behaviorFamilies: profileBehaviorFamilies(profile),
+  });
+  const previousSurfaces = new Set(previous?.families.surfaces.map(({ name }) => name) ?? []);
+  const unexpected = previous === null
+    ? []
+    : scan.families.surfaces.filter(({ name }) => !previousSurfaces.has(name));
+  const scannerBySurface = new Map(profile.localScanners.map((record) => [record.surface, record]));
+  const missingScanner = unexpected.some(({ name }) => !scannerBySurface.has(name));
+  const hasOpen = missingScanner || [...scan.families.surfaces, ...scan.families.behaviors]
+    .some(({ status }) => status === CENSUS_VERDICTS.open);
+  const candidate = {
+    ...scan,
+    profileReport: {
+      decisions: profile.decisions,
+      localScanners: profile.localScanners,
+      overrides: profile.overrides,
+    },
+    state: resolveCensusState({ enabled: profile.enabled, hasActive: true, hasOpen }),
+  };
+
+  if (previous !== null && serializeCensus(candidate) === serializeCensus(previous)) {
+    return { activated: false, activePath, candidate, profilePath };
+  }
+
+  await activateCensus({
+    activePath,
+    candidate,
+    verify: async (staged) => {
+      if (staged.state !== 'current') return false;
+      for (const { name } of unexpected) {
+        const record = scannerBySurface.get(name);
+        if (!record || !await runLocalScannerProof(root, record)) return false;
+      }
+      return staged.profileReport.decisions.every((decision) => (
+        decision.status !== CENSUS_VERDICTS.notRelevant || Boolean(decision.justification)
+      ));
+    },
+  });
+  return { activated: true, activePath, candidate, profilePath };
+}
+
+test('census-update is a published dual-surface own-work entry point', async () => {
+  const [source, mirror, manifestText, provenance, claudeOverview, codexOverview] = await Promise.all([
+    text('.claude/skills/census-update/SKILL.md'),
+    text('.agents/skills/census-update/SKILL.md'),
+    text('.claude/skills/skill-manifest.json'),
+    text('PROVENANCE.md'),
+    text('.claude/skills/setup-workflow/workflow-overview.md'),
+    text('.agents/skills/setup-workflow/workflow-overview.md'),
+  ]);
+  const entry = JSON.parse(manifestText).skills['census-update'];
+
+  assert.deepEqual(entry, {
+    class: 'generic',
+    publish: true,
+    entryPoint: true,
+    surfaces: ['claude', 'codex'],
+    provenance: 'own',
+  });
+  assert.equal(source, mirror);
+  assert.match(provenance, /Own work[\s\S]*census-update/);
+  assert.match(claudeOverview, /`census-update`/);
+  assert.match(codexOverview, /`census-update`/);
+});
+
+test('census-update coordinates the stable foundation API without a second engine', async () => {
+  const skill = await text('.claude/skills/census-update/SKILL.md');
+  for (const name of [
+    'scanCensus', 'serializeCensus', 'fingerprintCensus', 'CENSUS_BUILDER_VERSION',
+    'diffCensus', 'CENSUS_STATES', 'CENSUS_VERDICTS', 'resolveCensusState',
+    'activateCensus', 'CensusTransactionError',
+  ]) {
+    assert.match(skill, new RegExp(`\\b${name}\\b`), `${name} must remain the public mechanism`);
+  }
+  assert.match(skill, /do not copy, rename, or reimplement/i);
+  assert.match(skill, /Never ask the user which files, paths, or\s+patterns exist/i);
+  assert.match(skill, /recommendation and the evidence/i);
+  assert.match(skill, /`nicht relevant` requires a durable justification/i);
+  assert.match(skill, /override[\s\S]*must not[\s\S]*alter scanner facts/i);
+  assert.match(skill, /Work only in the current repository/i);
+  assert.match(skill, /Never[\s\S]*propose an upstream kit change/i);
+  assert.match(skill, /\.census\/profile\.json/);
+  assert.match(skill, /\.census\/active\.json/);
+  assert.match(skill, /schemaVersion/);
+});
+
+test('brownfield bootstrap activates real surface coverage with a separate behavior overview', async () => {
+  const root = await makeBrownfield();
+  const profilePath = join(root, PROFILE_RELATIVE_PATH);
+  try {
+    await assert.rejects(access(profilePath), (error) => error.code === 'ENOENT');
+    const facts = await scanCensus({ repoRoot: root, enabled: true });
+    assert.equal(facts.state, 'bootstrap');
+    await mkdir(join(root, '.census'), { recursive: true });
+    await writeFile(profilePath, `${JSON.stringify({
+      schemaVersion: 1,
+      enabled: true,
+      decisions: [
+        { family: 'authentication', status: CENSUS_VERDICTS.covered, evidence: 'apps/api/src' },
+        {
+          family: 'email-delivery',
+          status: CENSUS_VERDICTS.notRelevant,
+          justification: 'The product sends no email.',
+        },
+      ],
+      localScanners: [],
+      overrides: [],
+    })}\n`);
+
+    const { activePath, candidate } = await runConsumerCensus(root);
+    const persisted = await readJson(activePath);
+    const covered = persisted.families.surfaces
+      .filter(({ status }) => status === CENSUS_VERDICTS.covered).length;
+
+    assert.equal(candidate.state, 'current');
+    assert.equal(persisted.state, 'current');
+    assert.equal(`${covered} of ${persisted.families.surfaces.length}`, '3 of 3');
+    assert.deepEqual(persisted.families.behaviors, [
+      { name: 'authentication', status: 'abgedeckt', type: 'behavior' },
+      { name: 'email-delivery', status: 'nicht relevant', type: 'behavior' },
+    ]);
+    assert.equal(persisted.profileReport.decisions[1].justification, 'The product sends no email.');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a second unchanged current run performs no activation write', async () => {
+  const root = await makeBrownfield();
+  try {
+    await mkdir(join(root, '.census'), { recursive: true });
+    await writeFile(join(root, PROFILE_RELATIVE_PATH), `${JSON.stringify({
+      schemaVersion: 1,
+      enabled: true,
+      decisions: [],
+      localScanners: [],
+      overrides: [],
+    })}\n`);
+    const first = await runConsumerCensus(root);
+    assert.equal(first.activated, true);
+    const { activePath } = first;
+    const beforeBytes = await readFile(activePath, 'utf8');
+    const beforeStat = await stat(activePath);
+
+    const second = await runConsumerCensus(root);
+
+    assert.equal(second.activated, false);
+    assert.equal(await readFile(activePath, 'utf8'), beforeBytes);
+    assert.equal((await stat(activePath)).mtimeMs, beforeStat.mtimeMs);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an unexpected surface stays open despite not-relevant decisions and a change-local override', async () => {
+  const root = await makeBrownfield();
+  try {
+    await mkdir(join(root, '.census'), { recursive: true });
+    await writeFile(join(root, PROFILE_RELATIVE_PATH), `${JSON.stringify({
+      schemaVersion: 1,
+      enabled: true,
+      decisions: [{
+        family: 'postal-delivery',
+        justification: 'The product sends no physical mail.',
+        status: CENSUS_VERDICTS.notRelevant,
+      }],
+      localScanners: [],
+      overrides: [{ reason: 'Known formatting-only path delta.', scope: 'this change' }],
+    })}\n`);
+    await runConsumerCensus(root);
+    await mkdir(join(root, 'services/payments/src'), { recursive: true });
+    await writeFile(join(root, 'services/payments/src/index.mjs'), 'export const payments = true;\n');
+    await exec('git', ['add', 'services'], { cwd: root });
+    const before = await readJson(join(root, ACTIVE_RELATIVE_PATH));
+
+    await assert.rejects(runConsumerCensus(root), (error) => error.state === 'failed');
+    const after = await readJson(join(root, ACTIVE_RELATIVE_PATH));
+    assert.equal(serializeCensus(after), serializeCensus(before));
+    assert.equal(after.profileReport.decisions[0].status, 'nicht relevant');
+    assert.equal(after.profileReport.decisions[0].justification, 'The product sends no physical mail.');
+    assert.equal(after.profileReport.overrides[0].scope, 'this change');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a changed repository yields only compact path deltas and never reads a foreign repository', async () => {
+  const root = await makeBrownfield();
+  const foreign = await makeBrownfield();
+  try {
+    const reads = [];
+    const before = await scanCensus({ repoRoot: root });
+    await writeFile(join(root, 'apps/api/src/index.mjs'), 'export const api = "changed";\n');
+    const after = await scanCensus({
+      repoRoot: root,
+      readText: async (path) => {
+        reads.push(path);
+        return readFile(path, 'utf8');
+      },
+    });
+
+    assert.deepEqual(diffCensus(before, after), {
+      added: [],
+      changed: ['apps/api/src/index.mjs'],
+      open: [],
+      removed: [],
+    });
+    assert.ok(reads.length > 0);
+    assert.ok(reads.every((path) => path.startsWith(`${root}/`)));
+    assert.ok(reads.every((path) => !path.startsWith(`${foreign}/`)));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(foreign, { recursive: true, force: true });
+  }
+});
+
+test('an injected activation failure byte-preserves the active census', async () => {
+  const root = await makeBrownfield();
+  const activePath = join(root, '.census/active.json');
+  const previous = '{"generation":"known-good"}\n';
+  try {
+    await mkdir(join(root, '.census'), { recursive: true });
+    await writeFile(activePath, previous);
+    const candidate = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate,
+        verify: async () => true,
+        renameCandidate: async () => { throw new Error('injected swap failure'); },
+      }),
+      (error) => error.state === 'failed',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an unknown pattern activates only after a repository-local scanner test passes', async () => {
+  const root = await makeBrownfield();
+  try {
+    await mkdir(join(root, '.census'), { recursive: true });
+    const profilePath = join(root, PROFILE_RELATIVE_PATH);
+    await writeFile(profilePath, `${JSON.stringify({
+      schemaVersion: 1,
+      enabled: true,
+      decisions: [],
+      localScanners: [],
+      overrides: [],
+    })}\n`);
+    const { activePath } = await runConsumerCensus(root);
+    const previous = await readFile(activePath, 'utf8');
+    await mkdir(join(root, 'services/payments/src'), { recursive: true });
+    await writeFile(join(root, 'services/payments/src/index.mjs'), 'export const payments = true;\n');
+    await exec('git', ['add', 'services'], { cwd: root });
+
+    await assert.rejects(runConsumerCensus(root), (error) => error.state === 'failed');
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+
+    await mkdir(join(root, 'scripts/census-local'), { recursive: true });
+    await mkdir(join(root, 'test'), { recursive: true });
+    await writeFile(
+      join(root, 'scripts/census-local/scan-services.mjs'),
+      "export const scanServices = () => ['services/payments/src'];\n",
+    );
+    await writeFile(
+      join(root, 'test/census-services.test.mjs'),
+      "import { test } from 'node:test';\n"
+        + "import assert from 'node:assert/strict';\n"
+        + "import { scanServices } from '../scripts/census-local/scan-services.mjs';\n"
+        + "test('service scanner recognizes payments', () => {\n"
+        + "  assert.deepEqual(scanServices(), ['services/payments/src']);\n"
+        + "});\n",
+    );
+    await exec('git', ['add', 'services', 'scripts/census-local', 'test/census-services.test.mjs'], { cwd: root });
+    const withScanner = await readJson(profilePath);
+    withScanner.localScanners.push({
+      surface: 'services/payments/src',
+      module: 'scripts/census-local/scan-services.mjs',
+      export: 'scanServices',
+      test: 'test/census-services.test.mjs',
+    });
+    await writeFile(profilePath, `${JSON.stringify(withScanner)}\n`);
+
+    const { candidate } = await runConsumerCensus(root);
+    const activated = await readJson(activePath);
+    assert.equal(candidate.state, 'current');
+    assert.equal(activated.profileReport.localScanners[0].test, 'test/census-services.test.mjs');
+    assert.notEqual(await readFile(activePath, 'utf8'), previous);
+
+    const fingerprintBeforeOverride = fingerprintCensus(activated);
+    withScanner.overrides.push({ reason: 'display only', scope: 'this change' });
+    await writeFile(profilePath, `${JSON.stringify(withScanner)}\n`);
+    const raw = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    assert.deepEqual(fingerprintCensus(raw), fingerprintBeforeOverride);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('local scanner proof rejects absolute, escaping, and symlinked paths', async () => {
+  const root = await makeBrownfield();
+  const foreign = await mkdtemp(join(tmpdir(), 'awk-foreign-census-proof-'));
+  try {
+    await mkdir(join(root, '.census'), { recursive: true });
+    const profilePath = join(root, PROFILE_RELATIVE_PATH);
+    const profile = {
+      schemaVersion: 1,
+      enabled: true,
+      decisions: [],
+      localScanners: [],
+      overrides: [],
+    };
+    await writeFile(profilePath, `${JSON.stringify(profile)}\n`);
+    const { activePath } = await runConsumerCensus(root);
+    const previous = await readFile(activePath, 'utf8');
+    await mkdir(join(root, 'services/payments/src'), { recursive: true });
+    await writeFile(join(root, 'services/payments/src/index.mjs'), 'export const payments = true;\n');
+    await exec('git', ['add', 'services'], { cwd: root });
+
+    await writeFile(join(foreign, 'scanner.mjs'), "export const scanServices = () => ['services/payments/src'];\n");
+    await writeFile(
+      join(foreign, 'scanner.test.mjs'),
+      "import { test } from 'node:test'; test('foreign proof', () => {});\n",
+    );
+    const records = [
+      { module: join(foreign, 'scanner.mjs'), test: join(foreign, 'scanner.test.mjs') },
+      {
+        module: `../${basename(foreign)}/scanner.mjs`,
+        test: `../${basename(foreign)}/scanner.test.mjs`,
+      },
+    ];
+    await symlink(join(foreign, 'scanner.mjs'), join(root, 'scanner-link.mjs'));
+    await symlink(join(foreign, 'scanner.test.mjs'), join(root, 'scanner-link.test.mjs'));
+    records.push({ module: 'scanner-link.mjs', test: 'scanner-link.test.mjs' });
+
+    for (const record of records) {
+      profile.localScanners = [{
+        surface: 'services/payments/src',
+        export: 'scanServices',
+        ...record,
+      }];
+      await writeFile(profilePath, `${JSON.stringify(profile)}\n`);
+      await assert.rejects(runConsumerCensus(root), (error) => error.state === 'failed');
+      assert.equal(await readFile(activePath, 'utf8'), previous);
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(foreign, { recursive: true, force: true });
+  }
+});