@ikon85/agent-workflow-kit 0.13.0 → 0.15.0

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

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

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

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

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

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

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

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

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

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

package/PROVENANCE.md

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

package/README.md

@@ -332,6 +332,22 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.15.0
+
+- added: `.agents/skills/census-update/SKILL.md`
+- added: `.claude/skills/census-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
+### 0.14.0
+
+- added: `scripts/census/delta.mjs`
+- 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.15.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -37,6 +37,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/census-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "census-update",
+      "surface": "codex",
+      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/code-review/SKILL.md",
       "kind": "skill",
@@ -582,7 +591,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
+      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
       "mode": 420,
       "origin": "kit"
     },
@@ -893,6 +902,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/census-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "census-update",
+      "surface": "claude",
+      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/code-review/SKILL.md",
       "kind": "skill",
@@ -1564,7 +1582,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
+      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
       "mode": 420,
       "origin": "kit"
     },
@@ -1880,6 +1898,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.15.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {