@ikon85/agent-workflow-kit 0.14.0 → 0.16.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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-workflow
-description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, GitHub-Projects board field-IDs, spec-self-critique + spec-completeness seeds, workflow overview, and the deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
+description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, board field IDs, spec seeds, workflow overview, optional census choice, and deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
 disable-model-invocation: true
 ---
 
@@ -25,6 +25,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## 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) |
+| `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
 
 ## Idempotency contract — read before writing anything
 
@@ -54,6 +55,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CLAUDE.md` and `AGENTS.md` at the repo root — which exist? Do they already have a `## Workflow` / `## Agent skills` / `## Prod` block?
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
+- `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -105,6 +107,34 @@ For GitLab, local, other, or an unknown provider, give only a provider-neutral e
 
 **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`.
 
+### 2b. Section A3 — Optional project census
+
+> A project census is an optional, consumer-owned map that counts product
+> surfaces and lists behavior families separately. It can make later plans and
+> handoffs more complete, but setup cannot honestly claim coverage before the
+> repository has been scanned and verified.
+
+Read [census.md](./census.md) in full before presenting the choice. If
+`docs/agents/census.md` already records `yes`, `later`, or `no`, adopt that
+choice and do not prompt again on an ordinary setup rerun. Also adopt an
+existing, explicitly documented census path. If no choice exists, ask in plain
+language: *"Should setup prepare the optional project census now?"* Offer
+exactly:
+
+- **Yes** — create or adopt the project layer and minimal enabled profile, run
+  only the shipped self-test, and report the honest `bootstrap` / "not yet
+  meaningful" state. Do not scan, activate, or install a hook or gate.
+- **Later** — record a deferral. Create no census profile, hook, or gate; a
+  later explicit `census-update` invocation may activate without setup.
+- **No** — record the opt-out as `disabled`. Create no census profile, hook, or
+  gate and do not prompt again unless the user explicitly changes the choice.
+
+Use the complete `missing / yes / later / no / existing / explicit-enable /
+disable` matrix in the seed. A later explicit `census-update` invocation may
+activate without rerunning setup. Disable enforcement first, but retain every
+consumer-owned profile, scanner, test, and active snapshot unless the user
+separately approves deletion. Repeated runs are no-ops after reconciliation.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -182,6 +212,14 @@ Seed `docs/agents/code-review.md` from [code-review.md](./code-review.md) — th
 
 For each `docs/...` file: obey the idempotency contract (the "Idempotency contract" section). Prepend the sentinel with the resolved `state` (and `mode` for board-sync).
 
+For `docs/agents/census.md`, seed [census.md](./census.md), prepend the normal
+sentinel, and record the selected choice directly below it as
+`<!-- census: choice=<yes|later|no> -->`. On adoption, also record the discovered
+repository-relative profile and active-snapshot paths. Never overwrite a
+pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
+existing census are terminal for ordinary setup reruns. Only an explicit user
+request changes a recorded choice.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

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

@@ -0,0 +1,83 @@
+# Optional project census
+
+The census is a consumer-owned, counted map of product surfaces and behavior
+families. It is optional. Setup records only the user's choice; `census-update`
+does the factual scan, resolves ambiguity, verifies a candidate, and activates
+the result transactionally.
+
+## Setup state matrix
+
+| State or choice | Setup action | Observable result on repeat |
+|---|---|---|
+| `missing` | Explain the census in plain language and ask `yes / later / no`; do not infer an answer. | Ask again only while no choice has been recorded; write no hook or gate. |
+| `yes` | Create the minimal consumer-owned profile, or adopt the existing documented profile path. Set `enabled: true`, keep the active snapshot absent, run only the shipped census self-test, and report `bootstrap` / "not yet meaningful". | Adopt the same profile byte-for-byte; do not rescan, activate, or add another self-test. |
+| `later` | Record a retryable deferral outside the active profile. | Leave census files, hooks, and gates absent; an ordinary setup rerun is a no-op, while an explicit `census-update` may activate later. |
+| `no` | Record an explicit opt-out with census state `disabled`. | Keep the opt-out and do not create census files, hooks, or gates. |
+| `existing` | Adopt the repository's explicitly documented profile and active-snapshot paths without replacing consumer-owned content. Derive its state through the public census API. | Preserve every existing byte and report the derived state. |
+| `explicit-enable` | On a later explicit `census-update` invocation, let that skill scan, decide, verify, and transactionally activate without rerunning setup. | An unchanged verified census reports `current` and performs no write. |
+| `disable` | Set the profile to `enabled: false` transactionally and remove census hooks/gates from enforcement. | Stay `disabled`; retain consumer-owned profiles, scanners, tests, and snapshots unless the user separately approves their deletion. |
+
+## Deterministic setup effects
+
+The table below is the machine-checkable reference contract for setup. Its
+ordered `operations` are the only effects the setup proof may execute. Choice
+persistence always means `docs/agents/census.md`: the normal setup sentinel is
+the first line and `<!-- census: choice=<yes|later|no> -->` is the second.
+Paths under `retain` are consumer-owned evidence. Enforcement operations refer
+only to kit-owned wiring documented by the consumer; they are not permission to
+invent another census engine.
+
+```json census-setup-effects
+[
+  {"state":"missing","actor":"setup","choice":"none","operations":[],"retain":[],"repeat":"no-write"},
+  {"state":"yes","actor":"setup","choice":"yes","operations":["reconcile-choice-doc","reconcile-minimal-profile","derive-state","run-foundation-self-test"],"retain":[],"repeat":"no-write"},
+  {"state":"later","actor":"setup","choice":"later","operations":["reconcile-choice-doc"],"retain":[],"repeat":"no-write"},
+  {"state":"no","actor":"setup","choice":"no","operations":["reconcile-choice-doc","derive-state"],"retain":[],"repeat":"no-write"},
+  {"state":"existing","actor":"setup","choice":"recorded","operations":["adopt-choice-doc","derive-state"],"retain":["choice-doc","profile","active","scanner","scanner-test"],"repeat":"no-write"},
+  {"state":"explicit-enable","actor":"census-update","choice":"recorded","operations":["delegate-census-update","run-census-update-contract"],"retain":["choice-doc","profile","active","scanner","scanner-test"],"repeat":"no-write"},
+  {"state":"disable","actor":"census-update","choice":"recorded","operations":["remove-kit-hook","remove-kit-gate","update-profile-disabled","derive-state"],"retain":["choice-doc","profile-unknown-keys","active","scanner","scanner-test"],"repeat":"no-write"}
+]
+```
+
+## Bootstrap profile
+
+When `yes` creates the default `.census/profile.json`, write the deterministic
+profile shape documented by `census-update`: `schemaVersion: 1`, `enabled:
+true`, and empty `decisions`, `localScanners`, and `overrides` arrays. Do not
+create `.census/active.json`. Its absence is the evidence that the honest state
+is `bootstrap`, not `current`.
+
+Before writing, check for an existing repository convention and adopt it. A
+pre-existing profile remains consumer-owned: preserve unknown keys and do not
+replace its decisions. Never derive `current` from file presence; use
+`resolveCensusState` from `scripts/census/index.mjs`.
+
+Run the focused `scripts/census/state.test.mjs` census foundation self-test
+already shipped with the kit.
+A passing self-test proves the mechanism is available, not that this repository
+has been scanned. Setup must not install pre-commit, pre-push, CI, planning, or
+handoff gates for `yes`, `later`, or `no`.
+
+## Later activation and disable
+
+`later` and `no` are setup choices, not partially active censuses. A later,
+explicit `census-update` invocation is the sole activation route. Setup
+delegates this route to the shipped `census-update` contract and its focused
+`scripts/test_census_update_contract.test.mjs` proof; it does not reproduce
+activation, snapshots, or enforcement. Setup itself never calls `activateCensus`.
+
+Disable follows the ordered contract: remove the kit-owned hook, remove the
+kit-owned gate, then atomically replace only the profile's `enabled` value with
+`false`, preserving unknown keys, and verify `disabled` through
+`resolveCensusState`. Enforcement removal must finish before any profile
+mutation. Treat the choice document, local scanners, their tests, the profile,
+and the active snapshot as consumer-owned evidence. List those files and ask
+for separate deletion approval; without that approval, retain them.
+Setup never deletes consumer-owned files as part of disable.
+
+## Setup report
+
+Report the choice, adopted or created paths, derived state, self-test result,
+and whether enforcement changed. Name every action skipped on an idempotent
+rerun. Never claim surface coverage during setup: only `census-update` can
+produce a verified `X of Y` 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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-workflow
-description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, GitHub-Projects board field-IDs, spec-self-critique + spec-completeness seeds, workflow overview, and the deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
+description: "Scaffolds the project layer the portable workflow skills assume — issue tracker, triage labels, domain-doc layout, board field IDs, spec seeds, workflow overview, optional census choice, and deploy target. Writes `docs/agents/*`, `docs/conventions/spec-completeness.md`, and the `## Workflow` / `## Agent skills` / `## Prod` blocks in CLAUDE.md/AGENTS.md. Idempotent: a re-run reconciles per file/section and never overwrites filled content. Run once after installing the skills (or `npx <pkg> init`), or when a skill reports missing project-layer context. Adapted from Matt Pocock's `setup-matt-pocock-skills` (MIT)."
 disable-model-invocation: true
 ---
 
@@ -25,6 +25,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## 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) |
+| `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
 
 ## Idempotency contract — read before writing anything
 
@@ -54,6 +55,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CLAUDE.md` and `AGENTS.md` at the repo root — which exist? Do they already have a `## Workflow` / `## Agent skills` / `## Prod` block?
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
+- `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -105,6 +107,34 @@ For GitLab, local, other, or an unknown provider, give only a provider-neutral e
 
 **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`.
 
+### 2b. Section A3 — Optional project census
+
+> A project census is an optional, consumer-owned map that counts product
+> surfaces and lists behavior families separately. It can make later plans and
+> handoffs more complete, but setup cannot honestly claim coverage before the
+> repository has been scanned and verified.
+
+Read [census.md](./census.md) in full before presenting the choice. If
+`docs/agents/census.md` already records `yes`, `later`, or `no`, adopt that
+choice and do not prompt again on an ordinary setup rerun. Also adopt an
+existing, explicitly documented census path. If no choice exists, ask in plain
+language: *"Should setup prepare the optional project census now?"* Offer
+exactly:
+
+- **Yes** — create or adopt the project layer and minimal enabled profile, run
+  only the shipped self-test, and report the honest `bootstrap` / "not yet
+  meaningful" state. Do not scan, activate, or install a hook or gate.
+- **Later** — record a deferral. Create no census profile, hook, or gate; a
+  later explicit `census-update` invocation may activate without setup.
+- **No** — record the opt-out as `disabled`. Create no census profile, hook, or
+  gate and do not prompt again unless the user explicitly changes the choice.
+
+Use the complete `missing / yes / later / no / existing / explicit-enable /
+disable` matrix in the seed. A later explicit `census-update` invocation may
+activate without rerunning setup. Disable enforcement first, but retain every
+consumer-owned profile, scanner, test, and active snapshot unless the user
+separately approves deletion. Repeated runs are no-ops after reconciliation.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -182,6 +212,14 @@ Seed `docs/agents/code-review.md` from [code-review.md](./code-review.md) — th
 
 For each `docs/...` file: obey the idempotency contract (the "Idempotency contract" section). Prepend the sentinel with the resolved `state` (and `mode` for board-sync).
 
+For `docs/agents/census.md`, seed [census.md](./census.md), prepend the normal
+sentinel, and record the selected choice directly below it as
+`<!-- census: choice=<yes|later|no> -->`. On adoption, also record the discovered
+repository-relative profile and active-snapshot paths. Never overwrite a
+pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
+existing census are terminal for ordinary setup reruns. Only an explicit user
+request changes a recorded choice.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

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

@@ -0,0 +1,83 @@
+# Optional project census
+
+The census is a consumer-owned, counted map of product surfaces and behavior
+families. It is optional. Setup records only the user's choice; `census-update`
+does the factual scan, resolves ambiguity, verifies a candidate, and activates
+the result transactionally.
+
+## Setup state matrix
+
+| State or choice | Setup action | Observable result on repeat |
+|---|---|---|
+| `missing` | Explain the census in plain language and ask `yes / later / no`; do not infer an answer. | Ask again only while no choice has been recorded; write no hook or gate. |
+| `yes` | Create the minimal consumer-owned profile, or adopt the existing documented profile path. Set `enabled: true`, keep the active snapshot absent, run only the shipped census self-test, and report `bootstrap` / "not yet meaningful". | Adopt the same profile byte-for-byte; do not rescan, activate, or add another self-test. |
+| `later` | Record a retryable deferral outside the active profile. | Leave census files, hooks, and gates absent; an ordinary setup rerun is a no-op, while an explicit `census-update` may activate later. |
+| `no` | Record an explicit opt-out with census state `disabled`. | Keep the opt-out and do not create census files, hooks, or gates. |
+| `existing` | Adopt the repository's explicitly documented profile and active-snapshot paths without replacing consumer-owned content. Derive its state through the public census API. | Preserve every existing byte and report the derived state. |
+| `explicit-enable` | On a later explicit `census-update` invocation, let that skill scan, decide, verify, and transactionally activate without rerunning setup. | An unchanged verified census reports `current` and performs no write. |
+| `disable` | Set the profile to `enabled: false` transactionally and remove census hooks/gates from enforcement. | Stay `disabled`; retain consumer-owned profiles, scanners, tests, and snapshots unless the user separately approves their deletion. |
+
+## Deterministic setup effects
+
+The table below is the machine-checkable reference contract for setup. Its
+ordered `operations` are the only effects the setup proof may execute. Choice
+persistence always means `docs/agents/census.md`: the normal setup sentinel is
+the first line and `<!-- census: choice=<yes|later|no> -->` is the second.
+Paths under `retain` are consumer-owned evidence. Enforcement operations refer
+only to kit-owned wiring documented by the consumer; they are not permission to
+invent another census engine.
+
+```json census-setup-effects
+[
+  {"state":"missing","actor":"setup","choice":"none","operations":[],"retain":[],"repeat":"no-write"},
+  {"state":"yes","actor":"setup","choice":"yes","operations":["reconcile-choice-doc","reconcile-minimal-profile","derive-state","run-foundation-self-test"],"retain":[],"repeat":"no-write"},
+  {"state":"later","actor":"setup","choice":"later","operations":["reconcile-choice-doc"],"retain":[],"repeat":"no-write"},
+  {"state":"no","actor":"setup","choice":"no","operations":["reconcile-choice-doc","derive-state"],"retain":[],"repeat":"no-write"},
+  {"state":"existing","actor":"setup","choice":"recorded","operations":["adopt-choice-doc","derive-state"],"retain":["choice-doc","profile","active","scanner","scanner-test"],"repeat":"no-write"},
+  {"state":"explicit-enable","actor":"census-update","choice":"recorded","operations":["delegate-census-update","run-census-update-contract"],"retain":["choice-doc","profile","active","scanner","scanner-test"],"repeat":"no-write"},
+  {"state":"disable","actor":"census-update","choice":"recorded","operations":["remove-kit-hook","remove-kit-gate","update-profile-disabled","derive-state"],"retain":["choice-doc","profile-unknown-keys","active","scanner","scanner-test"],"repeat":"no-write"}
+]
+```
+
+## Bootstrap profile
+
+When `yes` creates the default `.census/profile.json`, write the deterministic
+profile shape documented by `census-update`: `schemaVersion: 1`, `enabled:
+true`, and empty `decisions`, `localScanners`, and `overrides` arrays. Do not
+create `.census/active.json`. Its absence is the evidence that the honest state
+is `bootstrap`, not `current`.
+
+Before writing, check for an existing repository convention and adopt it. A
+pre-existing profile remains consumer-owned: preserve unknown keys and do not
+replace its decisions. Never derive `current` from file presence; use
+`resolveCensusState` from `scripts/census/index.mjs`.
+
+Run the focused `scripts/census/state.test.mjs` census foundation self-test
+already shipped with the kit.
+A passing self-test proves the mechanism is available, not that this repository
+has been scanned. Setup must not install pre-commit, pre-push, CI, planning, or
+handoff gates for `yes`, `later`, or `no`.
+
+## Later activation and disable
+
+`later` and `no` are setup choices, not partially active censuses. A later,
+explicit `census-update` invocation is the sole activation route. Setup
+delegates this route to the shipped `census-update` contract and its focused
+`scripts/test_census_update_contract.test.mjs` proof; it does not reproduce
+activation, snapshots, or enforcement. Setup itself never calls `activateCensus`.
+
+Disable follows the ordered contract: remove the kit-owned hook, remove the
+kit-owned gate, then atomically replace only the profile's `enabled` value with
+`false`, preserving unknown keys, and verify `disabled` through
+`resolveCensusState`. Enforcement removal must finish before any profile
+mutation. Treat the choice document, local scanners, their tests, the profile,
+and the active snapshot as consumer-owned evidence. List those files and ask
+for separate deletion approval; without that approval, retain them.
+Setup never deletes consumer-owned files as part of disable.
+
+## Setup report
+
+Report the choice, adopted or created paths, derived state, self-test result,
+and whether enforcement changed. Name every action skipped on an idempotent
+rerun. Never claim surface coverage during setup: only `census-update` can
+produce a verified `X of Y` 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,