@ikon85/agent-workflow-kit 0.16.3 → 0.17.0

package/README.md

@@ -332,6 +332,15 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.17.0
+
+- added: `src/lib/release-preview.mjs`
+- added: `src/lib/semver.mjs`
+
+### 0.16.4
+
+- Metadata-only release.
+
 ### 0.16.3
 
 - changed: `.agents/skills/grill-me/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.16.3",
+  "kitVersion": "0.17.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -2069,6 +2069,20 @@
       "sha256": "24ce9373c464cc8363c53b0c690c3231cbf11362e6e08336e0e97663579d1f19",
       "mode": 493,
       "origin": "kit"
+    },
+    {
+      "path": "src/lib/release-preview.mjs",
+      "kind": "script",
+      "sha256": "a4e6627fac2d62812e44cfcb80c46539563734e7fa11f94b3dda37ff6fe6ae8f",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "src/lib/semver.mjs",
+      "kind": "script",
+      "sha256": "7d0a8da3740ed1eb79edb80f0eedb3cd1de47692d4886c6b119b39073a6468d1",
+      "mode": 420,
+      "origin": "kit"
     }
   ]
 }

package/docs/research/wave-43-script-hook-census.md

@@ -0,0 +1,128 @@
+# Wave 43 script and hook census
+
+Verified on 2026-07-15 against `agent-workflow-kit` commit
+`2d47dce23d9204b44951334c3c370bdb997c0943` and Testreporter commit
+[`458747ebe8d67f66840cb3c1e75284cf2be7fb20`](https://github.com/iKon85/Testreporter/tree/458747ebe8d67f66840cb3c1e75284cf2be7fb20).
+This is the research input for issue #59. It records facts only; it does not make
+ship, opt-in, profile-seam, or maintenance decisions.
+
+## Method and reconciliation
+
+The public-repository denominator is every tracked file below `scripts/**` and
+`.claude/hooks/**`, excluding `test_*.py`, `*.test.mjs`, and the metadata file
+`scripts/.npmignore`. The recount is:
+
+```text
+68 tracked entries
+- 31 tests
+-  1 metadata file
+= 36 current script/hook entries
+= 32 scripts + 4 hooks
+= 30 shipped helpers + 6 maintainer-only helpers
+```
+
+The shipped/helper split is derived from
+[`src/lib/bundle.mjs`](../../src/lib/bundle.mjs), whose `HELPER_FILES` list is
+the public distribution authority. The historical input is the 26-candidate
+list in [Testreporter #1976](https://github.com/iKon85/Testreporter/issues/1976),
+originally reconciled as 11 portable plus 15 generalize-first candidates in
+[Testreporter #1964](https://github.com/iKon85/Testreporter/issues/1964).
+
+Fresh exact-path comparison:
+
+```text
+Historical candidates:                       26/26 accounted for
+Still present at the exact Testreporter path: 26/26
+Present at the exact public-repo path:         0/26
+Proven exact rename in the public repo:        0/26
+Explicitly retired by a locked decision:       0/26
+```
+
+Therefore every historical row is classified as **present in the current
+consumer and absent from the current public denominator**. Related public
+primitives are called out only as inputs to the later grill; similarity is not
+treated as proof of a rename or as a ship decision.
+
+## Fresh public denominator: 36 of 36
+
+| Current path | Distribution status |
+|---|---|
+| `.claude/hooks/_hook_utils.py` | shipped helper |
+| `.claude/hooks/drift-guard.py` | shipped helper |
+| `.claude/hooks/skill-drift-hint.py` | shipped helper |
+| `.claude/hooks/sync-board-status.py` | shipped helper |
+| `scripts/anchor_table.py` | shipped helper |
+| `scripts/board-sync.py` | shipped helper |
+| `scripts/board_config.py` | shipped helper |
+| `scripts/board_fields.py` | shipped helper |
+| `scripts/build-kit.mjs` | maintainer-only |
+| `scripts/census/delta.mjs` | shipped helper |
+| `scripts/census/fingerprint.mjs` | shipped helper |
+| `scripts/census/index.mjs` | shipped helper |
+| `scripts/census/scan.mjs` | shipped helper |
+| `scripts/census/state.mjs` | shipped helper |
+| `scripts/census/transaction.mjs` | shipped helper |
+| `scripts/check-kit-staleness.mjs` | maintainer-only |
+| `scripts/execute-ready-check.py` | shipped helper |
+| `scripts/grill-census-wiring-guard.mjs` | maintainer-only |
+| `scripts/issue_deps.py` | shipped helper |
+| `scripts/kit-release.mjs` | shipped helper |
+| `scripts/kit-update-pr.mjs` | shipped helper |
+| `scripts/lib/audit-refs.mjs` | maintainer-only |
+| `scripts/lib/scrub.mjs` | maintainer-only |
+| `scripts/loc_offender_core.py` | shipped helper |
+| `scripts/loc_offender_gate.py` | shipped helper |
+| `scripts/node_kind.py` | shipped helper |
+| `scripts/portability_profile_scan.py` | maintainer-only |
+| `scripts/pr-body-check.py` | shipped helper |
+| `scripts/program_graph.py` | shipped helper |
+| `scripts/program_graph_parse.py` | shipped helper |
+| `scripts/program_graph_validate.py` | shipped helper |
+| `scripts/program_sync.py` | shipped helper |
+| `scripts/release-delta-guard.mjs` | shipped helper |
+| `scripts/release-parity.mjs` | shipped helper |
+| `scripts/release-state.mjs` | shipped helper |
+| `scripts/wrapup-land.py` | shipped helper |
+
+## Historical candidate crosswalk: 26 of 26
+
+All Testreporter links below are pinned to the verified consumer commit. “No
+dedicated tracked test found” means the fresh tracked-tree search found no test
+named for that candidate; it is not a statement about runtime correctness.
+
+| Historical candidate | Current public status and adjacent evidence | Current consumer dependency | Existing consumer test evidence |
+|---|---|---|---|
+| `scripts/audit_gate.py` | Exact path absent. | [`package.json#L44`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/package.json#L44) and `.githooks/pre-push` invoke it. | [`scripts/test_audit_gate.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_audit_gate.py), [`scripts/test_pre_push_audit_gate.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_pre_push_audit_gate.py) |
+| `scripts/cleanup-worktrees.sh` | Exact path absent. Public `scripts/wrapup-land.py` has adjacent worktree-cleanup behavior, not a proven rename. | No separate tracked consumer found beyond direct/manual use. | No dedicated tracked test found. |
+| `scripts/install-git-hooks.sh` | Exact path absent. | [`package.json#L45`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/package.json#L45) invokes it during postinstall. | [`scripts/test_install_git_hooks.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_install_git_hooks.py) |
+| `scripts/ensure-gitleaks.sh` | Exact path absent. | [`package.json#L45`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/package.json#L45) invokes it during postinstall; `docs/security/secret-scan.md` documents it. | No dedicated tracked test found. |
+| `.claude/hooks/block-bg-double-background.py` | Exact path absent. | [`.claude/settings.json#L85`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L85) wires it. | [`.claude/hooks/test_block_bg_double_background.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_block_bg_double_background.py) |
+| `.claude/hooks/block-npm-install-in-pnpm.py` | Exact path absent. | [`.claude/settings.json#L75`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L75) wires it. | [`.claude/hooks/test_block_npm_install_in_pnpm.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_block_npm_install_in_pnpm.py) |
+| `.claude/hooks/block-secrets.py` | Exact path absent. | [`.claude/settings.json#L56-L65`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L56-L65) wires it at two hook events. | [`.claude/hooks/test_block_secrets_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_block_secrets_smoke.py) |
+| `.claude/hooks/branch-watch.py` | Exact path absent. | [`.claude/settings.json#L161`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L161) wires it. | [`.claude/hooks/test_branch_watch_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_branch_watch_smoke.py) |
+| `.claude/hooks/grep-shim-guard.py` | Exact path absent. | [`.claude/settings.json#L80`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L80) wires it. | [`.claude/hooks/test_grep_shim_guard.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_grep_shim_guard.py) |
+| `.claude/hooks/recon-size-hint.py` | Exact path absent. | [`.claude/settings.json#L134`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L134) wires it. | [`.claude/hooks/test_recon_size_hint.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_recon_size_hint.py) |
+| `.claude/hooks/loc-offender-forewarn.py` | Exact path absent. Public `scripts/loc_offender_core.py` and `scripts/loc_offender_gate.py` are related shipped primitives, not a proven rename. | [`.claude/settings.json#L18`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L18) wires it. | [`scripts/test_loc_offender_forewarn.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_loc_offender_forewarn.py) |
+| `scripts/bump-version.sh` | Exact path absent. Public `scripts/kit-release.mjs` contains tested SemVer and metadata-update behavior, not a proven rename. | No separate consumer wiring found; the script is directly invoked. | No dedicated tracked test found for the historical script. |
+| `scripts/consolidate-memories.sh` | Exact path absent. | The two historical memory templates name it as their consolidator. | No dedicated tracked test found. |
+| `scripts/memory-templates/meta_decision_layer_choice.md` | Exact path absent. | Input consumed by `scripts/consolidate-memories.sh`. | No dedicated tracked test found. |
+| `scripts/memory-templates/meta_memory_lifecycle.md` | Exact path absent. | Input consumed by `scripts/consolidate-memories.sh`. | No dedicated tracked test found. |
+| `scripts/setup-worktree.sh` | Exact path absent. Public workflow prose allows a project helper or plain `git worktree add`; that is not a rename. | Central Testreporter worktree, port, and local-env setup primitive referenced by workflow documentation. | [`scripts/setup-worktree.test.mjs`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/setup-worktree.test.mjs), [`scripts/test_pre_push_loc_gate.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/scripts/test_pre_push_loc_gate.py) |
+| `.claude/hooks/baseline-capture-hint.py` | Exact path absent. | [`.claude/settings.json#L114`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L114) wires it. | [`.claude/hooks/test_baseline_capture_hint_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_baseline_capture_hint_smoke.py) |
+| `.claude/hooks/branch-context.py` | Exact path absent. | [`.claude/settings.json#L13`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L13) wires it. | [`.claude/hooks/test_branch_context_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_branch_context_smoke.py) |
+| `.claude/hooks/convention-drift-hint.py` | Exact path absent. Public `.claude/hooks/skill-drift-hint.py` and `drift-guard.py` are narrower adjacent mechanisms, not proven renames. | [`.claude/settings.json#L33`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L33) and rule `SOURCES.txt` files refer to it. | No dedicated tracked test found. |
+| `.claude/hooks/enforce-worktree.py` | Exact path absent. | [`.claude/settings.json#L109`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L109) wires it. | [`.claude/hooks/test_enforce_worktree.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_enforce_worktree.py) |
+| `.claude/hooks/enforce-worktree-cwd.py` | Exact path absent. | [`.claude/settings.json#L95`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L95) wires it. | [`.claude/hooks/test_enforce_worktree_cwd_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_enforce_worktree_cwd_smoke.py) |
+| `.claude/hooks/enforce-worktree-discipline.py` | Exact path absent. | [`.claude/settings.json#L70`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L70) wires it. | [`.claude/hooks/test_enforce_worktree_discipline_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_enforce_worktree_discipline_smoke.py) |
+| `.claude/hooks/migration-snapshot-reminder.py` | Exact path absent. | [`.claude/settings.json#L166`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L166) wires it. | [`.claude/hooks/test_migration_snapshot_reminder_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_migration_snapshot_reminder_smoke.py) |
+| `.claude/hooks/pre-refactor-sweep.py` | Exact path absent. | [`.claude/settings.json#L23`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L23) wires it. | [`.claude/hooks/test_pre_refactor_sweep.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_pre_refactor_sweep.py) |
+| `.claude/hooks/typecheck-on-stop.sh` | Exact path absent. | [`.claude/settings.json#L145`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L145) wires it. | No dedicated tracked test found. |
+| `.claude/hooks/slice-handoff-hint.py` | Exact path absent. | [`.claude/settings.json#L44`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/settings.json#L44) wires it. | [`.claude/hooks/test_slice_handoff_hint_smoke.py`](https://github.com/iKon85/Testreporter/blob/458747ebe8d67f66840cb3c1e75284cf2be7fb20/.claude/hooks/test_slice_handoff_hint_smoke.py) |
+
+## Inputs for the decision grill
+
+The crosswalk establishes the decision set but intentionally leaves its verdict
+columns blank. Issue #59 must decide, with the user, each row’s outcome, opt-in,
+profile seam, security and maintenance cost, and ship verdict. In particular,
+the adjacent public primitives identified above must be compared behaviorally
+before any row is called replaced, redundant, or already shipped.

package/package.json

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

@@ -9,6 +9,9 @@ import { execFileSync } from 'node:child_process';
 import { buildKit } from './build-kit.mjs';
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PUBLIC_CENSUS_UNIT = JSON.parse(await readFile(
+  join(REPO, 'test/fixtures/census-consumers/public-unit.json'), 'utf8',
+)).paths;
 async function withBuild(fn) {
   const dist = await mkdtemp(join(tmpdir(), 'awkit-build-'));
   try { return await fn(dist, await buildKit({ repoRoot: REPO, distDir: dist })); }
@@ -43,6 +46,19 @@ test('current build contains post-tag public files and repository metadata', asy
   });
 });
 
+test('current build contains the complete dual-surface census consumer unit', async () => {
+  await withBuild(async (dist, report) => {
+    const manifest = JSON.parse(await readFile(join(dist, 'agent-workflow-kit.package.json'), 'utf8'));
+    const paths = new Set(manifest.files.map(({ path }) => path));
+    assert.deepEqual(PUBLIC_CENSUS_UNIT.filter((path) => !paths.has(path)), []);
+    assert.equal(report.fileCount, manifest.files.length);
+    assert.equal(
+      await readFile(join(dist, '.claude/skills/census-update/SKILL.md'), 'utf8'),
+      await readFile(join(dist, '.agents/skills/census-update/SKILL.md'), 'utf8'),
+    );
+  });
+});
+
 test('current build is self-contained and never reaches into a consumer checkout', async () => {
   const source = await readFile(join(REPO, 'scripts/build-kit.mjs'), 'utf8');
   assert.doesNotMatch(source, /testreporter|tools\/agent-workflow-kit/);
@@ -67,6 +83,9 @@ test('npm pack keeps product files but excludes runtime residue', async () => {
     assert.ok(files.includes('scripts/kit-update-pr.mjs'));
     assert.ok(files.includes('.claude/hooks/drift-guard.py'));
     assert.ok(files.includes('.claude/skills/tdd/SKILL.md'));
+    for (const path of PUBLIC_CENSUS_UNIT) {
+      assert.ok(files.includes(path), `pack missing ${path}`);
+    }
     assert.ok(files.every((path) => !path.startsWith('.claude/logs/')));
     assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
     const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {

package/scripts/census-contract.test.mjs

@@ -0,0 +1,227 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  CENSUS_BUILDER_VERSION,
+  activateCensus,
+  diffCensus,
+  scanCensus,
+} from './census/index.mjs';
+
+const exec = promisify(execFile);
+const FIXTURES = new URL('../test/fixtures/census-consumers/', import.meta.url);
+const REPO = fileURLToPath(new URL('../', import.meta.url));
+
+async function consumer(name, tracked = ['.']) {
+  const root = await mkdtemp(join(tmpdir(), `awk-census-${name}-`));
+  await cp(new URL(`${name}/`, FIXTURES), root, { recursive: true });
+  await exec('git', ['init', '--quiet'], { cwd: root });
+  await exec('git', ['add', ...tracked], { cwd: root });
+  return root;
+}
+
+async function cleanup(root) {
+  await rm(root, { recursive: true, force: true });
+}
+
+async function json(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function backstopStatus(root) {
+  const { stdout } = await exec('python3', [
+    join(REPO, '.claude/hooks/drift-guard.py'), '--census-status',
+  ], { cwd: root });
+  return JSON.parse(stdout);
+}
+
+test('brownfield reports real X of Y surfaces separately from behaviors', async () => {
+  const root = await consumer('brownfield');
+  try {
+    const profile = await json(join(root, '.census/profile.json'));
+    const census = await scanCensus({
+      repoRoot: root,
+      enabled: profile.enabled,
+      hasActive: true,
+      behaviorFamilies: profile.decisions.map(({ family, status }) => ({ name: family, status })),
+    });
+    const covered = census.families.surfaces.filter(({ status }) => status === 'abgedeckt').length;
+
+    assert.equal(census.state, 'current');
+    assert.equal(`${covered} of ${census.families.surfaces.length}`, '3 of 3');
+    assert.deepEqual(census.families.behaviors, [
+      { name: 'authentication', status: 'abgedeckt', type: 'behavior' },
+      { name: 'email-delivery', status: 'nicht relevant', type: 'behavior' },
+    ]);
+    assert.ok(census.families.surfaces.every(({ type }) => type === 'surface'));
+  } finally { await cleanup(root); }
+});
+
+test('greenfield without an active snapshot remains honest bootstrap', async () => {
+  const root = await consumer('greenfield');
+  try {
+    const census = await scanCensus({ repoRoot: root, enabled: true, hasActive: false });
+    assert.equal(census.state, 'bootstrap');
+    assert.ok(census.denominator.length > 0, 'bootstrap still reports discovered facts');
+  } finally { await cleanup(root); }
+});
+
+test('unknown pattern stays open until its repository-local scanner test passes', async () => {
+  const root = await consumer('unknown-pattern', ['package.json', 'src', '.census']);
+  try {
+    const activePath = join(root, '.census/active.json');
+    const profilePath = join(root, '.census/profile.json');
+    const surface = 'services/payments/src';
+    const scannerRecord = {
+      surface,
+      module: 'scripts/census-local/scan-services.mjs',
+      export: 'scanServices',
+      test: 'test/census-services.test.mjs',
+    };
+
+    const untracked = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    assert.equal(untracked.state, 'refresh_required');
+    assert.deepEqual(diffCensus(untracked, untracked).open, [surface]);
+
+    // Establish real active history before the repository grows the unknown surface.
+    await rm(join(root, 'services'), { recursive: true });
+    await rm(join(root, 'scripts'), { recursive: true });
+    await rm(join(root, 'test'), { recursive: true });
+    const known = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    await writeFile(activePath, `${JSON.stringify({
+      ...known,
+      profileReport: { decisions: [], localScanners: [], overrides: [] },
+    })}\n`);
+
+    await cp(new URL('unknown-pattern/services/', FIXTURES), join(root, 'services'), { recursive: true });
+    await exec('git', ['add', 'services'], { cwd: root });
+    const trackedOnly = await backstopStatus(root);
+    assert.equal(trackedOnly.state, 'refresh_required');
+    assert.ok(trackedOnly.reasons.includes('topology'));
+
+    const profile = await json(profilePath);
+    profile.localScanners.push(scannerRecord);
+    await writeFile(profilePath, `${JSON.stringify(profile)}\n`);
+    const missingProof = await backstopStatus(root);
+    assert.equal(missingProof.state, 'refresh_required');
+    assert.ok(missingProof.reasons.includes(`proof:${surface}`));
+
+    await cp(new URL('unknown-pattern/scripts/', FIXTURES), join(root, 'scripts'), { recursive: true });
+    await cp(new URL('unknown-pattern/test/', FIXTURES), join(root, 'test'), { recursive: true });
+    await writeFile(
+      join(root, scannerRecord.test),
+      "import { test } from 'node:test'; test('failing local proof', () => { throw new Error('no'); });\n",
+    );
+    await exec('git', ['add', 'scripts', 'test', '.census/profile.json'], { cwd: root });
+    const failedProof = await backstopStatus(root);
+    assert.equal(failedProof.state, 'refresh_required');
+    assert.ok(failedProof.reasons.includes(`proof:${surface}`));
+
+    await cp(
+      new URL('unknown-pattern/test/census-services.test.mjs', FIXTURES),
+      join(root, scannerRecord.test),
+    );
+    const candidate = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    assert.equal(candidate.state, 'current');
+    await activateCensus({
+      activePath,
+      candidate: {
+        ...candidate,
+        profileReport: { decisions: [], localScanners: [scannerRecord], overrides: [] },
+      },
+      verify: async () => {
+        await exec('node', ['--test', scannerRecord.test], { cwd: root });
+        const scanner = await import(`${pathToFileURL(join(root, scannerRecord.module)).href}?proof=${Date.now()}`);
+        return scanner[scannerRecord.export]().includes(surface);
+      },
+    });
+
+    const proven = await backstopStatus(root);
+    assert.equal(proven.state, 'current');
+    assert.deepEqual(proven.reasons, []);
+    const active = await json(activePath);
+    assert.equal(active.profileReport.localScanners[0].test, scannerRecord.test);
+  } finally { await cleanup(root); }
+});
+
+test('scan and compact delta do not overwrite a consumer-local modification', async () => {
+  const root = await consumer('local-modified');
+  try {
+    const sourcePath = join(root, 'src/index.mjs');
+    const activePath = join(root, '.census/active.json');
+    const sourceBefore = await readFile(sourcePath);
+    const activeBefore = await readFile(activePath);
+    const previous = { denominator: [], families: { surfaces: [], behaviors: [] } };
+    const current = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    const delta = diffCensus(previous, current);
+
+    assert.deepEqual(Object.keys(delta), ['added', 'changed', 'open', 'removed']);
+    assert.ok(JSON.stringify(delta).length < JSON.stringify(current).length);
+    assert.deepEqual(await readFile(sourcePath), sourceBefore);
+    assert.deepEqual(await readFile(activePath), activeBefore);
+  } finally { await cleanup(root); }
+});
+
+test('secret canary is absent from scan, delta, and file reads', async () => {
+  const root = await consumer('secret-canary');
+  try {
+    const reads = [];
+    const scan = await scanCensus({
+      repoRoot: root,
+      readText: async (path) => {
+        reads.push(path);
+        return readFile(path, 'utf8');
+      },
+    });
+    const output = JSON.stringify({ scan, delta: diffCensus({ denominator: [] }, scan) });
+    assert.doesNotMatch(output, /CENSUS_SECRET_CANARY/);
+    assert.ok(reads.every((path) => !path.includes('credentials')));
+  } finally { await cleanup(root); }
+});
+
+test('interrupted activation preserves the active census byte-for-byte', async () => {
+  const root = await consumer('interrupted');
+  try {
+    const activePath = join(root, '.census/active.json');
+    const before = await readFile(activePath);
+    const candidate = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    await assert.rejects(activateCensus({
+      activePath,
+      candidate,
+      verify: async () => true,
+      renameCandidate: async () => { throw new Error('fixture interruption'); },
+    }), (error) => error.state === 'failed');
+    assert.deepEqual(await readFile(activePath), before);
+  } finally { await cleanup(root); }
+});
+
+test('consumer update reports a newer builder without silently mutating its census', async () => {
+  const root = await consumer('consumer-update');
+  try {
+    const activePath = join(root, '.census/active.json');
+    const profilePath = join(root, '.census/profile.json');
+    const fresh = await scanCensus({ repoRoot: root, enabled: true, hasActive: true });
+    await writeFile(activePath, `${JSON.stringify({
+      ...fresh,
+      fingerprints: { ...fresh.fingerprints, builder: 'older-builder-fingerprint' },
+      profileReport: { decisions: [], localScanners: [], overrides: [] },
+    })}\n`);
+    const activeBefore = await readFile(activePath);
+    const profileBefore = await readFile(profilePath);
+    const { stdout } = await exec('python3', [
+      join(REPO, '.claude/hooks/drift-guard.py'), '--census-status',
+    ], { cwd: root });
+    const status = JSON.parse(stdout);
+
+    assert.equal(status.state, 'refresh_required');
+    assert.equal(status.detail, `builder ${CENSUS_BUILDER_VERSION}`);
+    assert.ok(status.reasons.includes('builder'));
+    assert.deepEqual(await readFile(activePath), activeBefore);
+    assert.deepEqual(await readFile(profilePath), profileBefore);
+  } finally { await cleanup(root); }
+});

package/scripts/test_census_forward_contract.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Forward proof: a clean public checkout builds and serves census consumers."""
+import json
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+PUBLIC_UNIT_RELATIVE = Path("test/fixtures/census-consumers/public-unit.json")
+GREENFIELD_RELATIVE = Path("test/fixtures/census-consumers/greenfield")
+
+
+class CensusForwardContract(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp(prefix="awk-census-forward-"))
+        self.addCleanup(shutil.rmtree, self.tmp, ignore_errors=True)
+        self.public = self.tmp / "public-kit"
+        self.public.mkdir()
+        source_root = REPO
+        self.forbidden_source_root = str(source_root)
+        archive = subprocess.Popen(
+            ["git", "archive", "HEAD"], cwd=source_root, stdout=subprocess.PIPE
+        )
+        unpack = subprocess.run(
+            ["tar", "-x", "-C", str(self.public)], stdin=archive.stdout,
+            capture_output=True, timeout=30,
+        )
+        archive.stdout.close()
+        archive_rc = archive.wait(timeout=30)
+        self.assertEqual((archive_rc, unpack.returncode), (0, 0), unpack.stderr.decode())
+        # From this boundary onward every executable, fixture, and assertion input
+        # is resolved inside the archived public checkout.
+        self.assertTrue((self.public / GREENFIELD_RELATIVE).is_dir())
+        self.assertTrue((self.public / PUBLIC_UNIT_RELATIVE).is_file())
+        build = subprocess.run(
+            ["node", "scripts/build-kit.mjs"], cwd=self.public,
+            capture_output=True, text=True, timeout=120,
+        )
+        self.assertEqual(build.returncode, 0, build.stderr)
+        self.dist = self.public / "dist-kit"
+
+    def test_built_public_checkout_exercises_both_surfaces_and_scanner(self):
+        claude = (self.dist / ".claude/skills/census-update/SKILL.md").read_text()
+        codex = (self.dist / ".agents/skills/census-update/SKILL.md").read_text()
+        self.assertEqual(claude, codex)
+        for public_export in ("scanCensus", "diffCensus", "activateCensus"):
+            self.assertIn(public_export, claude)
+
+        consumer = self.tmp / "consumer"
+        fixture = self.public / GREENFIELD_RELATIVE
+        self.assertTrue(fixture.is_relative_to(self.public))
+        shutil.copytree(fixture, consumer)
+        subprocess.run(["git", "init", "--quiet"], cwd=consumer, check=True)
+        subprocess.run(["git", "add", "."], cwd=consumer, check=True)
+        runner = (
+            "import { scanCensus } from "
+            + json.dumps((self.dist / "scripts/census/index.mjs").as_uri())
+            + "; const result = await scanCensus({repoRoot: process.argv[1], enabled:true});"
+            + "console.log(JSON.stringify({state:result.state,count:result.denominator.length}));"
+        )
+        run = subprocess.run(
+            ["node", "--input-type=module", "--eval", runner, str(consumer)],
+            cwd=self.public, capture_output=True, text=True, timeout=30,
+        )
+        self.assertEqual(run.returncode, 0, run.stderr)
+        self.assertEqual(json.loads(run.stdout), {"state": "bootstrap", "count": 2})
+        self.assertNotIn("testreporter", run.stdout.lower())
+        self.assertNotIn(self.forbidden_source_root, runner)
+        self.assertNotIn(self.forbidden_source_root, run.stdout)
+
+    def test_public_pack_contains_complete_census_unit_without_foreign_reach(self):
+        pack = subprocess.run(
+            ["npm", "pack", "--dry-run", "--json"], cwd=self.public,
+            capture_output=True, text=True, timeout=120,
+        )
+        self.assertEqual(pack.returncode, 0, pack.stderr)
+        paths = {entry["path"] for entry in json.loads(pack.stdout)[0]["files"]}
+        expected = set(json.loads(
+            (self.public / PUBLIC_UNIT_RELATIVE).read_text(encoding="utf-8")
+        )["paths"])
+        self.assertEqual(expected - paths, set())
+        for path in expected:
+            text = (self.public / path).read_text(encoding="utf-8")
+            self.assertNotIn("tools/agent-workflow-kit", text)
+            self.assertNotIn("testreporter", text.lower())
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_dist_kit_smoke.py

@@ -194,6 +194,27 @@ class DistKitValidateGraphSmoke(unittest.TestCase):
                          "language (fields.status.roles / --status-role) instead:\n"
                          + "\n".join(hits))
 
+    def test_shipped_census_runs_for_a_foreign_greenfield_on_both_surfaces(self):
+        consumer = self.tmp / "census-consumer"
+        shutil.copytree(REPO / "test/fixtures/census-consumers/greenfield", consumer)
+        subprocess.run(["git", "init", "--quiet"], cwd=consumer, check=True)
+        subprocess.run(["git", "add", "."], cwd=consumer, check=True)
+        claude = (DIST / ".claude/skills/census-update/SKILL.md").read_text()
+        codex = (DIST / ".agents/skills/census-update/SKILL.md").read_text()
+        self.assertEqual(claude, codex)
+        module = (DIST / "scripts/census/index.mjs").as_uri()
+        runner = (
+            f'import {{ scanCensus }} from {json.dumps(module)};'
+            "const r=await scanCensus({repoRoot:process.argv[1],enabled:true});"
+            "console.log(JSON.stringify({state:r.state,count:r.denominator.length}));"
+        )
+        result = subprocess.run(
+            ["node", "--input-type=module", "--eval", runner, str(consumer)],
+            cwd=DIST, capture_output=True, text=True, timeout=30,
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout), {"state": "bootstrap", "count": 2})
+
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)

package/scripts/test_skill_publish_audit.py

@@ -36,6 +36,9 @@ import unittest
 from pathlib import Path
 
 REPO = Path(__file__).resolve().parent.parent
+PUBLIC_CENSUS_UNIT = json.loads(
+    (REPO / "test/fixtures/census-consumers/public-unit.json").read_text(encoding="utf-8")
+)["paths"]
 PUBLIC_SLUG = "iKon85/agent-workflow-kit"
 CREDIT_FILES = {"LICENSE", "README.md", "PROVENANCE.md", "THIRD-PARTY-NOTICES.md"}
 PRIVATE_SKILLS = {
@@ -295,6 +298,19 @@ class RealDistKitIsClean(unittest.TestCase):
         violations = audit_dir(REPO / "dist-kit")
         self.assertEqual(violations, [], "\n".join(violations[:40]))
 
+    def test_built_dist_kit_contains_publishable_census_without_foreign_reach(self):
+        build = subprocess.run(
+            ["node", str(REPO / "scripts/build-kit.mjs")], cwd=REPO,
+            capture_output=True, text=True, timeout=120,
+        )
+        self.assertEqual(build.returncode, 0, build.stderr)
+        for rel in PUBLIC_CENSUS_UNIT:
+            path = REPO / "dist-kit" / rel
+            self.assertTrue(path.is_file(), f"missing published census resource: {rel}")
+            text = path.read_text(encoding="utf-8")
+            self.assertNotIn("tools/agent-workflow-kit", text)
+            self.assertNotIn("testreporter", text.lower())
+
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)

package/src/lib/bundle.mjs

@@ -47,6 +47,10 @@ export const HELPER_FILES = [
   // the parity primitive rather than growing a second registry/GitHub comparison.
   { path: 'scripts/release-parity.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/release-state.mjs', kind: 'script', mode: 0o644 },
+  // Consumer-owned project release profiles use these read-only shared
+  // primitives before any apply/commit/tag action is allowed.
+  { path: 'src/lib/semver.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/release-preview.mjs', kind: 'script', mode: 0o644 },
   // 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 },

package/src/lib/release-preview.mjs

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { nextVersion, parseSemver } from './semver.mjs';
+
+export const PROJECT_RELEASE_PROFILE = 'docs/agents/workflow-capabilities.json';
+
+export async function loadProjectReleaseProfile(consumerRoot) {
+  const profile = JSON.parse(
+    await readFile(join(consumerRoot, PROJECT_RELEASE_PROFILE), 'utf8'),
+  );
+  if (profile.schemaVersion !== 1 || !profile.projectRelease) {
+    throw new Error('project release profile must contain schemaVersion 1 and projectRelease');
+  }
+  if (!Array.isArray(profile.projectRelease.versionFiles)
+      || profile.projectRelease.versionFiles.length === 0) {
+    throw new Error('project release profile requires at least one versionFiles entry');
+  }
+  return profile.projectRelease;
+}
+
+async function readVersionFile(consumerRoot, path) {
+  const raw = await readFile(join(consumerRoot, path), 'utf8');
+  const body = JSON.parse(raw);
+  return {
+    path,
+    version: body.version,
+    sha256: createHash('sha256').update(raw).digest('hex'),
+  };
+}
+
+export async function previewProjectRelease(options) {
+  const {
+    consumerRoot, profile, requestedVersion,
+    repositoryFacts = { dirtyPaths: [], existingTags: [] },
+  } = options;
+  const files = await Promise.all(
+    profile.versionFiles.map((path) => readVersionFile(consumerRoot, path)),
+  );
+  const currentVersion = files[0].version;
+  const paths = files.map(({ path }) => path);
+  const invalidFiles = files.filter(({ version }) => {
+    try { parseSemver(version); return false; } catch { return true; }
+  });
+  if (invalidFiles.length) {
+    return {
+      status: 'blocked',
+      summary: {
+        currentVersion,
+        targetVersion: null,
+        packageCount: paths.length,
+        synchronizedFiles: paths,
+      },
+      blockers: [{
+        code: 'invalid-current-version',
+        files: invalidFiles.map(({ path, version }) => ({ path, version })),
+      }],
+      actions: [],
+      repositoryFacts,
+    };
+  }
+  let targetVersion;
+  try {
+    targetVersion = nextVersion(currentVersion, requestedVersion);
+  } catch {
+    return {
+      status: 'blocked',
+      summary: {
+        currentVersion,
+        targetVersion: null,
+        packageCount: paths.length,
+        synchronizedFiles: paths,
+      },
+      blockers: [{ code: 'invalid-target-version', requestedVersion }],
+      actions: [],
+      repositoryFacts,
+    };
+  }
+  const tag = `${profile.tagPrefix ?? 'v'}${targetVersion}`;
+  const blockers = [];
+  if (files.some(({ version }) => version !== currentVersion)) {
+    blockers.push({
+      code: 'divergent-versions',
+      files: files.map(({ path, version }) => ({ path, version })),
+    });
+  }
+  const dirtyTargets = paths.filter((path) => repositoryFacts.dirtyPaths.includes(path));
+  if (dirtyTargets.length) blockers.push({ code: 'dirty-targets', paths: dirtyTargets });
+  if (repositoryFacts.existingTags.includes(tag)) {
+    blockers.push({ code: 'existing-tag', tag });
+  }
+  const snapshot = files.map(({ path, sha256 }) => ({ path, sha256 }));
+  const confirmation = createHash('sha256').update(JSON.stringify({
+    currentVersion, targetVersion, snapshot, tag,
+  })).digest('hex');
+  return {
+    status: blockers.length ? 'blocked' : 'ready',
+    summary: {
+      currentVersion,
+      targetVersion,
+      packageCount: paths.length,
+      synchronizedFiles: paths,
+    },
+    blockers,
+    actions: [
+      { type: 'write-version', version: targetVersion, paths },
+      { type: 'commit', message: `chore: prepare project release ${targetVersion}` },
+      { type: 'tag', name: tag },
+    ],
+    repositoryFacts,
+    snapshot,
+    confirmation,
+  };
+}

package/src/lib/semver.mjs

@@ -0,0 +1,25 @@
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export function parseSemver(version) {
+  const match = SEMVER.exec(version);
+  if (!match) throw new Error(`invalid semver: ${version}`);
+  return match.slice(1).map(Number);
+}
+
+export function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return Math.sign(a[index] - b[index]);
+  }
+  return 0;
+}
+
+export function nextVersion(current, requested) {
+  const [major, minor, patch] = parseSemver(current);
+  if (requested === 'major') return `${major + 1}.0.0`;
+  if (requested === 'minor') return `${major}.${minor + 1}.0`;
+  if (requested === 'patch') return `${major}.${minor}.${patch + 1}`;
+  parseSemver(requested);
+  return requested;
+}