@ikon85/agent-workflow-kit 0.12.0 → 0.14.0

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

@@ -24,6 +24,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
 | `## 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) |
 
 ## Idempotency contract — read before writing anything
 
@@ -68,6 +69,40 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 
 Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
 
+### 2a. Automatic Kit update pull requests (GitHub tracker only)
+
+> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+
+Also read the repository Actions policy before enabling:
+
+```bash
+gh api repos/<owner>/<repo>/actions/permissions/workflow
+```
+
+The response must report `"can_approve_pull_request_reviews": true`; this is GitHub's **Allow GitHub Actions to create and approve pull requests** gate used by the stable PR upsert. If it is false, or the policy cannot be read, do not seed the workflow yet. Guide the user to **Settings → Actions → General → Workflow permissions**, enable that checkbox, and rerun `setup-workflow`.
+
+If the user prefers `gh`, first show the exact mutation and obtain **explicit confirmation**; never change repository settings merely because setup was invoked. After confirmation, preserve the currently reported `default_workflow_permissions` value (`read` or `write`) and set the gate with:
+
+```bash
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow \
+  -f default_workflow_permissions=<current-read-or-write> \
+  -F can_approve_pull_request_reviews=true
+```
+
+Read the policy back and offer **Enable** only after the field is actually true.
+
+- **Enable** — seed `.github/workflows/agent-workflow-kit-update.yml` from [assets/agent-workflow-kit-update.yml](./assets/agent-workflow-kit-update.yml).
+- **Opt out** — do not create a GitHub workflow, branch, or pull request.
+- **Ask later** — do not create a GitHub workflow, branch, or pull request; explain that re-running `setup-workflow` can offer it again.
+
+This workflow opt-in has its own file-level idempotency rule: if the destination is already present, leave it byte-for-byte unchanged and report `skipped (already present)`. On repeated setup runs, do not prompt again when it exists. The workflow consumes the scoped `@ikon85/agent-workflow-kit` release and its existing parity-checked transactional update command; do not reproduce either mechanism in setup prose or shell steps.
+
+For GitLab, local, other, or an unknown provider, give only a provider-neutral explanation that automatic updates require provider-specific CI and pull-request support; **do not create a GitHub workflow**. Setup itself never creates the update branch or pull request — only an opted-in workflow run may do that later.
+
 **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`.
 
 ### 3. Section B — Triage labels

package/.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -0,0 +1,31 @@
+name: Agent Workflow Kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: agent-workflow-kit-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.14
+      - name: Install locked consumer dependencies
+        run: npm ci --ignore-scripts
+      - name: Verify, test, and upsert the Kit update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

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

@@ -24,6 +24,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
 | `## 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) |
 
 ## Idempotency contract — read before writing anything
 
@@ -68,6 +69,40 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 
 Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
 
+### 2a. Automatic Kit update pull requests (GitHub tracker only)
+
+> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+
+Also read the repository Actions policy before enabling:
+
+```bash
+gh api repos/<owner>/<repo>/actions/permissions/workflow
+```
+
+The response must report `"can_approve_pull_request_reviews": true`; this is GitHub's **Allow GitHub Actions to create and approve pull requests** gate used by the stable PR upsert. If it is false, or the policy cannot be read, do not seed the workflow yet. Guide the user to **Settings → Actions → General → Workflow permissions**, enable that checkbox, and rerun `setup-workflow`.
+
+If the user prefers `gh`, first show the exact mutation and obtain **explicit confirmation**; never change repository settings merely because setup was invoked. After confirmation, preserve the currently reported `default_workflow_permissions` value (`read` or `write`) and set the gate with:
+
+```bash
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow \
+  -f default_workflow_permissions=<current-read-or-write> \
+  -F can_approve_pull_request_reviews=true
+```
+
+Read the policy back and offer **Enable** only after the field is actually true.
+
+- **Enable** — seed `.github/workflows/agent-workflow-kit-update.yml` from [assets/agent-workflow-kit-update.yml](./assets/agent-workflow-kit-update.yml).
+- **Opt out** — do not create a GitHub workflow, branch, or pull request.
+- **Ask later** — do not create a GitHub workflow, branch, or pull request; explain that re-running `setup-workflow` can offer it again.
+
+This workflow opt-in has its own file-level idempotency rule: if the destination is already present, leave it byte-for-byte unchanged and report `skipped (already present)`. On repeated setup runs, do not prompt again when it exists. The workflow consumes the scoped `@ikon85/agent-workflow-kit` release and its existing parity-checked transactional update command; do not reproduce either mechanism in setup prose or shell steps.
+
+For GitLab, local, other, or an unknown provider, give only a provider-neutral explanation that automatic updates require provider-specific CI and pull-request support; **do not create a GitHub workflow**. Setup itself never creates the update branch or pull request — only an opted-in workflow run may do that later.
+
 **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`.
 
 ### 3. Section B — Triage labels

package/.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -0,0 +1,31 @@
+name: Agent Workflow Kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: agent-workflow-kit-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.14
+      - name: Install locked consumer dependencies
+        run: npm ci --ignore-scripts
+      - name: Verify, test, and upsert the Kit update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

package/README.md

@@ -332,6 +332,23 @@ 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`
+- added: `.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- added: `scripts/kit-update-pr.mjs`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
 ### 0.12.0
 
 - added: `.agents/skills/kit-update/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.12.0",
+  "kitVersion": "0.14.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -460,6 +460,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/board-sync.md",
       "kind": "skill",
@@ -528,7 +537,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "ea0b75ccd1579820a09e7c8d4c151126aa0be7a0be6b76b23599fadebb44b554",
+      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
       "mode": 420,
       "origin": "kit"
     },
@@ -1433,6 +1442,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/board-sync.md",
       "kind": "skill",
@@ -1501,7 +1519,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "ea0b75ccd1579820a09e7c8d4c151126aa0be7a0be6b76b23599fadebb44b554",
+      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
       "mode": 420,
       "origin": "kit"
     },
@@ -1862,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",
@@ -1883,6 +1943,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/kit-update-pr.mjs",
+      "kind": "script",
+      "sha256": "64e7818003d7c6db227eadad0b114e199399a52a96965ab2f0f496c0a1e5c79c",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/loc_offender_core.py",
       "kind": "script",

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.12.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": {
-    "agent-workflow-kit": "src/cli.mjs"
+    "agent-workflow-kit": "src/cli.mjs",
+    "agent-workflow-kit-update-pr": "scripts/kit-update-pr.mjs"
   },
   "scripts": {
     "test": "npm run test:node && npm run test:python",

package/scripts/build-kit.test.mjs

@@ -37,6 +37,9 @@ test('current build contains post-tag public files and repository metadata', asy
     const pkg = JSON.parse(await readFile(join(dist, 'package.json'), 'utf8'));
     assert.equal(pkg.name, '@ikon85/agent-workflow-kit');
     assert.equal(pkg.repository.url, 'git+https://github.com/iKon85/agent-workflow-kit.git');
+    assert.equal(pkg.bin['agent-workflow-kit'], 'src/cli.mjs');
+    assert.equal(pkg.bin['agent-workflow-kit-update-pr'], 'scripts/kit-update-pr.mjs');
+    await readFile(join(dist, 'scripts/kit-update-pr.mjs'));
   });
 });
 
@@ -52,9 +55,31 @@ test('npm pack keeps the complete scripts tree but excludes Python caches', () =
   const files = JSON.parse(output)[0].files.map((file) => file.path);
   assert.ok(files.includes('scripts/build-kit.mjs'));
   assert.ok(files.includes('scripts/board-sync.py'));
+  assert.ok(files.includes('scripts/kit-update-pr.mjs'));
   assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
   const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {
     cwd: REPO, encoding: 'utf8',
   }));
   assert.ok(pkg.files.includes('scripts/'), 'package must ship future script file types');
 });
+
+test('packed scoped artifact keeps the existing npx default-bin inference', async () => {
+  const destination = await mkdtemp(join(tmpdir(), 'awkit-pack-'));
+  try {
+    const packed = JSON.parse(execFileSync('npm', [
+      'pack', '--pack-destination', destination, '--json',
+    ], { cwd: REPO, encoding: 'utf8' }));
+    const output = execFileSync('npx', [
+      '--yes', '--offline', `./${packed[0].filename}`,
+    ], { cwd: destination, encoding: 'utf8' });
+    assert.match(output, /Usage: agent-workflow-kit/);
+
+    const updater = execFileSync('npm', [
+      'exec', '--yes', '--offline', `--package=./${packed[0].filename}`,
+      '--', 'agent-workflow-kit-update-pr', 'help',
+    ], { cwd: destination, encoding: 'utf8' });
+    assert.match(updater, /Usage: agent-workflow-kit-update-pr/);
+  } finally {
+    await rm(destination, { recursive: true, force: true });
+  }
+});

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`;
+}