@ikon85/agent-workflow-kit 0.13.0 → 0.14.0

package/README.md

@@ -332,6 +332,15 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.14.0
+
+- added: `scripts/census/delta.mjs`
+- added: `scripts/census/fingerprint.mjs`
+- added: `scripts/census/index.mjs`
+- added: `scripts/census/scan.mjs`
+- added: `scripts/census/state.mjs`
+- added: `scripts/census/transaction.mjs`
+
 ### 0.13.0
 
 - added: `.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.13.0",
+  "kitVersion": "0.14.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -1880,6 +1880,48 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "scripts/census/delta.mjs",
+      "kind": "script",
+      "sha256": "b4f92ecb4bf1920bd62707c83f308269385bc5e35c2205abc97d8d8b849ade84",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/census/fingerprint.mjs",
+      "kind": "script",
+      "sha256": "fbb25d9f53ab74a9bdffc5db816a56f0d976204b74c2126b8ec7c11e8c8d54fc",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/census/index.mjs",
+      "kind": "script",
+      "sha256": "ef87d073842dec13f27c929e573e064314fdd704aeeec85e80d526c044f23a9a",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/census/scan.mjs",
+      "kind": "script",
+      "sha256": "0988282c8aa6f1e1644eab924fab6e5e306c5a8bb3c26175ff74080d8de673d9",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/census/state.mjs",
+      "kind": "script",
+      "sha256": "588fb5bd3a3855fd7acdf9c056c63e0a04f94308b91f48b9be18807ca849fab7",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/census/transaction.mjs",
+      "kind": "script",
+      "sha256": "63a27f4b28583178bfc08fd6ac553528d9d955e1ec06bc37f779824d5fcaa92f",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "scripts/execute-ready-check.py",
       "kind": "script",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.13.0",
+  "version": "0.14.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/census/census.test.mjs

@@ -0,0 +1,252 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { cp, mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CENSUS_VERDICTS,
+  diffCensus,
+  scanCensus,
+  serializeCensus,
+} from './index.mjs';
+
+const exec = promisify(execFile);
+const FIXTURE = new URL('../../test/fixtures/census-recipes/known/', import.meta.url);
+
+async function makeRepository() {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-'));
+  await cp(FIXTURE, root, { recursive: true });
+  await exec('git', ['init', '--quiet'], { cwd: root });
+  await exec('git', ['add', '.'], { cwd: root });
+  await exec('git', ['add', '-f', 'ignored/src/ignored.mjs'], { cwd: root });
+  return root;
+}
+
+test('known recipe scans are byte-identical and separate denominator from evidence', async () => {
+  const root = await makeRepository();
+  try {
+    const first = await scanCensus({ repoRoot: root });
+    const second = await scanCensus({ repoRoot: root });
+
+    assert.equal(serializeCensus(first), serializeCensus(second));
+    assert.deepEqual(first.denominator.map(({ path }) => path), [
+      'package.json',
+      'src/index.mjs',
+    ]);
+    assert.deepEqual(first.evidence.map(({ path }) => path), [
+      'docs/architecture.md',
+      'test/index.test.mjs',
+    ]);
+    assert.equal(first.fingerprints.builder.length, 64);
+    assert.equal(first.fingerprints.topology.length, 64);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('scan state reflects explicit activation and active-census facts', async () => {
+  const root = await makeRepository();
+  try {
+    assert.equal((await scanCensus({ repoRoot: root })).state, 'disabled');
+    assert.equal((await scanCensus({ repoRoot: root, enabled: true })).state, 'bootstrap');
+    assert.equal((await scanCensus({ repoRoot: root, enabled: true, hasActive: true })).state, 'current');
+
+    await mkdir(join(root, 'new-service', 'src'), { recursive: true });
+    await writeFile(join(root, 'new-service', 'src', 'index.mjs'), 'export const newService = true;\n');
+    assert.equal(
+      (await scanCensus({ repoRoot: root, enabled: true, hasActive: true })).state,
+      'refresh_required',
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('secret, ignored, generated, and vendor paths are never read or counted', async () => {
+  const root = await makeRepository();
+  try {
+    const reads = [];
+    const result = await scanCensus({
+      repoRoot: root,
+      readText: async (path) => {
+        reads.push(path);
+        return (await import('node:fs/promises')).readFile(path, 'utf8');
+      },
+    });
+    const output = serializeCensus(result);
+
+    assert.ok(!reads.some((path) => path.includes('secrets')));
+    assert.ok(!reads.some((path) => path.includes('credentials')));
+    assert.ok(!output.includes('CENSUS_SECRET_CANARY'));
+    assert.ok(!output.includes('secrets/'));
+    assert.ok(!output.includes('credentials.txt'));
+    assert.ok(!output.includes('vendor/src'));
+    assert.ok(!output.includes('dist/src'));
+    assert.ok(!output.includes('ignored/src'));
+    assert.equal(result.denominator.length, 2);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('tracked product symlinks stay unread and force an open refresh', async () => {
+  const root = await makeRepository();
+  const external = await mkdtemp(join(tmpdir(), 'awk-census-external-'));
+  const externalPath = join(external, 'canary.mjs');
+  await writeFile(externalPath, 'CENSUS_EXTERNAL_SECRET_CANARY\n');
+  await symlink(externalPath, join(root, 'src', 'external.mjs'));
+  await exec('git', ['add', 'src/external.mjs'], { cwd: root });
+  try {
+    const reads = [];
+    const result = await scanCensus({
+      repoRoot: root,
+      enabled: true,
+      hasActive: true,
+      readText: async (path) => {
+        reads.push(path);
+        return (await import('node:fs/promises')).readFile(path, 'utf8');
+      },
+    });
+
+    assert.ok(!reads.includes(join(root, 'src', 'external.mjs')));
+    assert.ok(!reads.includes(externalPath));
+    assert.ok(!serializeCensus(result).includes('CENSUS_EXTERNAL_SECRET_CANARY'));
+    assert.ok(!result.denominator.some(({ path }) => path === 'src/external.mjs'));
+    assert.deepEqual(result.families.surfaces, [
+      { name: 'production-config', status: 'abgedeckt', type: 'surface' },
+      { name: 'src', status: 'offen', type: 'surface' },
+    ]);
+    assert.equal(result.state, 'refresh_required');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(external, { recursive: true, force: true });
+  }
+});
+
+test('a tracked product file missing from the working tree forces an open refresh', async () => {
+  const root = await makeRepository();
+  try {
+    await rm(join(root, 'src', 'index.mjs'));
+
+    const result = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+
+    assert.deepEqual(result.denominator.map(({ path }) => path), ['package.json']);
+    assert.deepEqual(result.families.surfaces, [
+      { name: 'production-config', status: 'abgedeckt', type: 'surface' },
+      { name: 'src', status: 'offen', type: 'surface' },
+    ]);
+    assert.equal(result.state, 'refresh_required');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an unreadable tracked product file makes its family open without a duplicate covered verdict', async () => {
+  const root = await makeRepository();
+  try {
+    const result = await scanCensus({
+      repoRoot: root,
+      enabled: true,
+      hasActive: true,
+      readText: async (path) => {
+        if (path === join(root, 'src', 'index.mjs')) throw new Error('simulated unreadable product file');
+        return (await import('node:fs/promises')).readFile(path, 'utf8');
+      },
+    });
+
+    assert.deepEqual(result.families.surfaces, [
+      { name: 'production-config', status: 'abgedeckt', type: 'surface' },
+      { name: 'src', status: 'offen', type: 'surface' },
+    ]);
+    assert.equal(result.state, 'refresh_required');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an untracked source root is open and prevents current', async () => {
+  const root = await makeRepository();
+  try {
+    await mkdir(join(root, 'new-service', 'src'), { recursive: true });
+    await writeFile(join(root, 'new-service', 'src', 'index.mjs'), 'export const newService = true;\n');
+
+    const result = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+
+    assert.equal(result.state, 'refresh_required');
+    assert.deepEqual(result.families.surfaces.filter(({ status }) => status === 'offen'), [
+      { name: 'new-service/src', status: 'offen', type: 'surface' },
+    ]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('delta reports compact path changes and open families', async () => {
+  const root = await makeRepository();
+  try {
+    const previous = await scanCensus({ repoRoot: root });
+    await writeFile(join(root, 'src', 'index.mjs'), 'export const answer = 43;\n');
+    await mkdir(join(root, 'new-service', 'src'), { recursive: true });
+    await writeFile(join(root, 'new-service', 'src', 'index.mjs'), 'export const newService = true;\n');
+    const next = await scanCensus({ repoRoot: root });
+
+    assert.deepEqual(diffCensus(previous, next), {
+      added: [],
+      changed: ['src/index.mjs'],
+      open: ['new-service/src'],
+      removed: [],
+    });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('content-only edits do not change the topology fingerprint', async () => {
+  const root = await makeRepository();
+  try {
+    const previous = await scanCensus({ repoRoot: root });
+    await writeFile(join(root, 'src', 'index.mjs'), 'export const answer = 99;\n');
+    const next = await scanCensus({ repoRoot: root });
+
+    assert.equal(previous.fingerprints.topology, next.fingerprints.topology);
+    assert.deepEqual(diffCensus(previous, next).changed, ['src/index.mjs']);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('family verdicts expose every machine-readable contract value', () => {
+  assert.deepEqual(CENSUS_VERDICTS, {
+    covered: 'abgedeckt',
+    notRelevant: 'nicht relevant',
+    open: 'offen',
+  });
+});
+
+test('behavior families represent covered, not-relevant, and open verdicts separately', async () => {
+  const root = await makeRepository();
+  try {
+    const result = await scanCensus({
+      repoRoot: root,
+      enabled: true,
+      hasActive: true,
+      behaviorFamilies: [
+        { name: 'auth-session', status: CENSUS_VERDICTS.covered },
+        { name: 'billing', status: CENSUS_VERDICTS.notRelevant },
+        { name: 'email-delivery', status: CENSUS_VERDICTS.open },
+      ],
+    });
+
+    assert.deepEqual(result.families.behaviors, [
+      { name: 'auth-session', status: 'abgedeckt', type: 'behavior' },
+      { name: 'billing', status: 'nicht relevant', type: 'behavior' },
+      { name: 'email-delivery', status: 'offen', type: 'behavior' },
+    ]);
+    assert.ok(result.families.surfaces.every(({ type }) => type === 'surface'));
+    assert.equal(result.state, 'refresh_required');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/scripts/census/delta.mjs

@@ -0,0 +1,14 @@
+function byPath(census) {
+  return new Map(census.denominator.map((entry) => [entry.path, entry.hash]));
+}
+
+export function diffCensus(previous, next) {
+  const before = byPath(previous);
+  const after = byPath(next);
+  const added = [...after.keys()].filter((path) => !before.has(path)).sort();
+  const removed = [...before.keys()].filter((path) => !after.has(path)).sort();
+  const changed = [...after.keys()].filter((path) => before.has(path) && before.get(path) !== after.get(path)).sort();
+  const open = [...next.families.surfaces, ...next.families.behaviors]
+    .filter(({ status }) => status === 'offen').map(({ name }) => name).sort();
+  return { added, changed, open, removed };
+}

package/scripts/census/fingerprint.mjs

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+
+export const CENSUS_BUILDER_VERSION = '1';
+
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function fingerprintCensus({ denominator, evidence, families }) {
+  const structural = (entries) => entries.map(({ family, kind, path }) => ({ family, kind, path }));
+  const topology = {
+    denominator: structural(denominator),
+    evidence: structural(evidence),
+    families,
+  };
+  return {
+    builder: sha256(`agent-workflow-kit-census:${CENSUS_BUILDER_VERSION}`),
+    topology: sha256(JSON.stringify(topology)),
+  };
+}

package/scripts/census/index.mjs

@@ -0,0 +1,9 @@
+export { scanCensus } from './scan.mjs';
+export { CENSUS_BUILDER_VERSION, fingerprintCensus } from './fingerprint.mjs';
+export { CENSUS_STATES, CENSUS_VERDICTS, resolveCensusState } from './state.mjs';
+export { diffCensus } from './delta.mjs';
+export { activateCensus, CensusTransactionError } from './transaction.mjs';
+
+export function serializeCensus(census) {
+  return `${JSON.stringify(census)}\n`;
+}

package/scripts/census/scan.mjs

@@ -0,0 +1,174 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fingerprintCensus, sha256 } from './fingerprint.mjs';
+import { CENSUS_VERDICTS, resolveCensusState } from './state.mjs';
+
+const exec = promisify(execFile);
+const EVIDENCE_PARTS = new Set(['docs', 'test', 'tests', '__tests__']);
+const EXCLUDED_PARTS = new Set([
+  '.git', '.next', 'build', 'coverage', 'dist', 'generated', 'node_modules', 'vendor',
+]);
+const CONFIG_NAMES = new Set([
+  'package.json', 'tsconfig.json', 'vite.config.js', 'vite.config.mjs',
+  'vite.config.ts', 'next.config.js', 'next.config.mjs', 'Dockerfile',
+]);
+
+function pathParts(path) {
+  return path.split('/');
+}
+
+function isEvidence(path) {
+  const parts = pathParts(path);
+  return parts.some((part) => EVIDENCE_PARTS.has(part))
+    || /(?:^|\.)test\.[^.]+$/.test(path)
+    || /(?:^|\.)spec\.[^.]+$/.test(path)
+    || /(?:^|\/)README(?:\.[^/]*)?$/.test(path);
+}
+
+function isSecret(path) {
+  return pathParts(path).some((part) => {
+    const name = part.toLowerCase();
+    return name === '.env' || name.startsWith('.env.')
+      || /^(?:secrets?|credentials?)(?:[._-]|$)/.test(name)
+      || /private[-_.]?key/.test(name);
+  });
+}
+
+function isExcluded(path) {
+  return pathParts(path).some((part) => EXCLUDED_PARTS.has(part));
+}
+
+function isProduct(path) {
+  const parts = pathParts(path);
+  if (CONFIG_NAMES.has(parts.at(-1))) return true;
+  return parts.some((part) => ['src', 'app', 'apps', 'lib', 'packages'].includes(part));
+}
+
+function familyFor(path, kind) {
+  if (kind === 'config') return 'production-config';
+  const parts = pathParts(path);
+  const rootIndex = parts.findIndex((part) => ['src', 'app', 'apps', 'lib', 'packages'].includes(part));
+  const packageRoot = ['apps', 'packages'].includes(parts[rootIndex]);
+  return parts.slice(0, Math.min(rootIndex + (packageRoot ? 2 : 1), parts.length)).join('/');
+}
+
+async function gitPaths(repoRoot, args) {
+  const { stdout } = await exec('git', args, { cwd: repoRoot, encoding: 'utf8' });
+  return stdout.split('\0').filter(Boolean).sort();
+}
+
+async function gitIgnoredPaths(repoRoot, paths) {
+  if (!paths.length) return new Set();
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', ['check-ignore', '--no-index', '-z', '--stdin'], { cwd: repoRoot });
+    const chunks = [];
+    child.stdout.on('data', (chunk) => chunks.push(chunk));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0 && code !== 1) return reject(new Error(`git check-ignore exited ${code}`));
+      resolve(new Set(Buffer.concat(chunks).toString('utf8').split('\0').filter(Boolean)));
+    });
+    child.stdin.end(`${paths.join('\0')}\0`);
+  });
+}
+
+async function regularContainedPath(repoRoot, realRepoRoot, path) {
+  const candidate = resolve(repoRoot, path);
+  const lexicalRelative = relative(resolve(repoRoot), candidate);
+  if (lexicalRelative === '..' || lexicalRelative.startsWith(`..${sep}`) || isAbsolute(lexicalRelative)) {
+    return null;
+  }
+  let stats;
+  let canonical;
+  try {
+    stats = await lstat(candidate);
+    // Symlinks, including links that resolve inside the repository, are excluded.
+    // Only a regular file whose canonical path remains inside the repository may be read.
+    if (!stats.isFile()) return null;
+    canonical = await realpath(candidate);
+  } catch {
+    return null;
+  }
+  const canonicalRelative = relative(realRepoRoot, canonical);
+  if (canonicalRelative === '..' || canonicalRelative.startsWith(`..${sep}`) || isAbsolute(canonicalRelative)) {
+    return null;
+  }
+  return candidate;
+}
+
+function behaviorSummary(entries) {
+  const verdicts = new Set(Object.values(CENSUS_VERDICTS));
+  return entries.map(({ name, status }) => {
+    if (typeof name !== 'string' || !name) throw new TypeError('behavior family requires a name');
+    if (!verdicts.has(status)) throw new TypeError(`invalid behavior family verdict: ${status}`);
+    return { name, status, type: 'behavior' };
+  }).sort((left, right) => {
+    const leftKey = `${left.name}\0${left.status}`;
+    const rightKey = `${right.name}\0${right.status}`;
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+}
+
+function surfaceSummary(entries, openPaths) {
+  const statuses = new Map(entries.map(({ family }) => [family, CENSUS_VERDICTS.covered]));
+  for (const path of openPaths) {
+    if (isProduct(path) && !isExcluded(path) && !isSecret(path)) {
+      const kind = CONFIG_NAMES.has(pathParts(path).at(-1)) ? 'config' : 'source';
+      statuses.set(familyFor(path, kind), CENSUS_VERDICTS.open);
+    }
+  }
+  return [...statuses].sort(([left], [right]) => (
+    left < right ? -1 : left > right ? 1 : 0
+  )).map(([name, status]) => ({
+    name, status, type: 'surface',
+  }));
+}
+
+export async function scanCensus({
+  repoRoot,
+  behaviorFamilies = [],
+  enabled = false,
+  hasActive = false,
+  readText = (path) => readFile(path, 'utf8'),
+}) {
+  const realRepoRoot = await realpath(repoRoot);
+  const tracked = await gitPaths(repoRoot, ['ls-files', '-z']);
+  const untracked = await gitPaths(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z']);
+  const ignored = await gitIgnoredPaths(repoRoot, tracked);
+  const denominator = [];
+  const evidence = [];
+  const openPaths = [...untracked];
+  for (const path of tracked) {
+    if (ignored.has(path) || isSecret(path) || isExcluded(path)) continue;
+    const target = isEvidence(path) ? evidence : isProduct(path) ? denominator : null;
+    if (!target) continue;
+    const readablePath = await regularContainedPath(repoRoot, realRepoRoot, path);
+    if (!readablePath) {
+      if (target === denominator) openPaths.push(path);
+      continue;
+    }
+    let content;
+    try {
+      content = await readText(readablePath);
+    } catch {
+      if (target === denominator) openPaths.push(path);
+      continue;
+    }
+    const kind = CONFIG_NAMES.has(pathParts(path).at(-1)) ? 'config' : 'source';
+    target.push({ family: familyFor(path, kind), hash: sha256(content), kind, path });
+  }
+  const families = {
+    surfaces: surfaceSummary(denominator, openPaths),
+    behaviors: behaviorSummary(behaviorFamilies),
+  };
+  const result = { denominator, evidence, families };
+  const hasOpen = [...families.surfaces, ...families.behaviors]
+    .some(({ status }) => status === CENSUS_VERDICTS.open);
+  return {
+    ...result,
+    fingerprints: fingerprintCensus(result),
+    state: resolveCensusState({ enabled, hasActive, hasOpen }),
+  };
+}

package/scripts/census/state.mjs

@@ -0,0 +1,23 @@
+export const CENSUS_STATES = Object.freeze([
+  'disabled',
+  'bootstrap',
+  'current',
+  'refresh_required',
+  'updating',
+  'failed',
+]);
+
+export const CENSUS_VERDICTS = Object.freeze({
+  covered: 'abgedeckt',
+  notRelevant: 'nicht relevant',
+  open: 'offen',
+});
+
+export function resolveCensusState({ enabled, hasActive, hasOpen = false, updating = false, failed = false }) {
+  if (!enabled) return 'disabled';
+  if (updating) return 'updating';
+  if (failed) return 'failed';
+  if (!hasActive) return 'bootstrap';
+  if (hasOpen) return 'refresh_required';
+  return 'current';
+}

package/scripts/census/state.test.mjs

@@ -0,0 +1,15 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CENSUS_STATES, resolveCensusState } from './index.mjs';
+
+test('state resolver implements the complete census state contract', () => {
+  assert.deepEqual(CENSUS_STATES, [
+    'disabled', 'bootstrap', 'current', 'refresh_required', 'updating', 'failed',
+  ]);
+  assert.equal(resolveCensusState({ enabled: false }), 'disabled');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: false }), 'bootstrap');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true }), 'current');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true, hasOpen: true }), 'refresh_required');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true, updating: true }), 'updating');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true, failed: true }), 'failed');
+});

package/scripts/census/transaction.mjs

@@ -0,0 +1,50 @@
+import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export class CensusTransactionError extends Error {
+  constructor(message, state, cause) {
+    super(message, { cause });
+    this.name = 'CensusTransactionError';
+    this.state = state;
+  }
+}
+async function acquireLock(lockPath) {
+  await mkdir(dirname(lockPath), { recursive: true });
+  try {
+    const handle = await open(lockPath, 'wx');
+    await handle.close();
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      throw new CensusTransactionError(`census update already locked: ${lockPath}`, 'updating', error);
+    }
+    throw error;
+  }
+}
+
+/** Stage, verify, then atomically replace the active census while holding a local lock. */
+export async function activateCensus({
+  activePath,
+  candidate,
+  verify,
+  lockPath = `${activePath}.lock`,
+  stagePath = `${activePath}.candidate`,
+  renameCandidate = rename,
+}) {
+  if (typeof verify !== 'function') {
+    throw new TypeError('census activation requires a callable verifier');
+  }
+  await acquireLock(lockPath);
+  try {
+    const serialized = `${JSON.stringify(candidate)}\n`;
+    await writeFile(stagePath, serialized, 'utf8');
+    const verified = await verify(candidate, { activePath, stagePath });
+    if (verified === false) throw new Error('census candidate verification returned false');
+    await renameCandidate(stagePath, activePath);
+    return { activePath, state: 'current' };
+  } catch (error) {
+    await rm(stagePath, { force: true });
+    throw new CensusTransactionError(`census activation failed: ${error.message}`, 'failed', error);
+  } finally {
+    await rm(lockPath, { force: true });
+  }
+}

package/scripts/census/transaction.test.mjs

@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { activateCensus } from './index.mjs';
+
+test('activation requires a callable verifier before staging or swapping', async () => {
+  for (const verify of [undefined, 'not-callable']) {
+    const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+    const activePath = join(root, 'active.json');
+    const previous = '{"generation":"previous"}\n';
+    await writeFile(activePath, previous);
+    let swapped = false;
+    try {
+      await assert.rejects(
+        activateCensus({
+          activePath,
+          candidate: { generation: 'next' },
+          renameCandidate: async () => { swapped = true; },
+          verify,
+        }),
+        /callable verifier/,
+      );
+      assert.equal(await readFile(activePath, 'utf8'), previous);
+      await assert.rejects(readFile(`${activePath}.candidate`), { code: 'ENOENT' });
+      await assert.rejects(readFile(`${activePath}.lock`), { code: 'ENOENT' });
+      assert.equal(swapped, false);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+});
+
+test('verify failure preserves active bytes and a second run can succeed', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+  const activePath = join(root, 'active.json');
+  const previous = '{"generation":"previous"}\n';
+  await writeFile(activePath, previous);
+  try {
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate: { generation: 'next' },
+        verify: async () => { throw new Error('fixture verify failure'); },
+      }),
+      (error) => error.state === 'failed',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+
+    const result = await activateCensus({
+      activePath,
+      candidate: { generation: 'next' },
+      verify: async ({ generation }) => generation === 'next',
+    });
+    assert.equal(result.state, 'current');
+    assert.equal(await readFile(activePath, 'utf8'), '{"generation":"next"}\n');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('swap failure preserves active bytes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+  const activePath = join(root, 'active.json');
+  const previous = '{"generation":"previous"}\n';
+  await writeFile(activePath, previous);
+  try {
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate: { generation: 'next' },
+        renameCandidate: async () => { throw new Error('fixture swap failure'); },
+        verify: async () => true,
+      }),
+      (error) => error.state === 'failed',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an existing local lock reports updating without touching active bytes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+  const activePath = join(root, 'active.json');
+  const previous = '{"generation":"previous"}\n';
+  await writeFile(activePath, previous);
+  await writeFile(`${activePath}.lock`, 'held\n');
+  try {
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate: { generation: 'next' },
+        verify: async () => true,
+      }),
+      (error) => error.state === 'updating',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/lib/bundle.mjs

@@ -50,6 +50,14 @@ export const HELPER_FILES = [
   // GitHub-consumer automation: invokes the existing update command, then owns
   // only the stable tested branch/pull-request upsert.
   { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },
+  // Stdlib-only project census foundation. index.mjs is the stable consumer
+  // entrypoint; its five local modules must ship with it as one helper unit.
+  { path: 'scripts/census/index.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/census/scan.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/census/fingerprint.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/census/delta.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/census/state.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/census/transaction.mjs', kind: 'script', mode: 0o644 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.