@ikon85/agent-workflow-kit 0.15.0 → 0.16.1

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/to-prd/SKILL.md

@@ -76,6 +76,24 @@ gh project item-list 1 --owner <owner> --limit 500 --format json   # check targe
    - `<!-- prd-source-id: <id> -->` + `<!-- prd-content-fp: <hash> -->` (see step 3).
 5. **Mode B label normalization:** if the reused issue carries wrong/multiple `type:*`, missing `priority:*`, `ready-for-agent`, or `needs-info` → **normalize onto the PRD contract** (exactly one `type:*`, one `priority:*`, no `ready-for-agent`/`needs-info`). Exception per the discriminator (§2): `type:cluster` always, or Wave **without** `wave-stub` → **no** normalization, **hard stop** (step 2); a `wave-stub`-labeled Stufe-1p target normalizes normally — it is a valid Mode B target.
 
+### Census freshness before a cross-cutting lock
+
+When the PRD claims completeness across several product surfaces, run
+`python3 .claude/hooks/drift-guard.py --census-status` before the board write.
+An activated census reporting `refresh_required` means the cross-cutting PRD
+must not be locked: run `$census-update`, resolve every open surface, and retry.
+`disabled`, `no_census`, `bootstrap`, or `offline` stays visible and fail-open;
+perform and report the existing manual walk instead. This gate does not apply
+to an orthogonal, surface-local PRD.
+
+A justified change-local override may acknowledge only a proven mechanical
+false positive. It must carry `scope: "this change"`, a non-empty `reason`, and
+the exact `topologyFingerprint` reported as `change_binding` by the current
+status check. That binding is valid only for those freshly scanned topology
+facts; a later topology change makes the persisted override stale. The
+override never changes scanner facts, builder/topology fingerprints, open
+verdicts, or state resolution, and therefore cannot green real drift.
+
 ## 4b. Program-PRD body (mode=program)
 
 mode=program writes the Program-PRD per `.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md` instead of the `<prd-template>` below — a **parallel** grammar for the program altitude, not a replacement (a Feature-PRD keeps using `<prd-template>` unchanged). It carries: the `## Scope` chapter with stable Scope-Item IDs (`S1`, `S2`, …), the machine-parsable `## Wellenplan` table (`Welle | Status | Name | Phase | Slices | Gate | covers`), the `## Phasen-Gates` checklist (only when the program uses phases), the `## Slices` per-slice detail chapter (one `####` section per planned slice, per `SLICE-METADATA-FORMAT.md`'s grammar), and the Abbruch-Konvention. `scripts/program_graph.py` (`board-sync.py validate-graph`) is the parser — to-prd writes the shape, it does not itself validate the graph (that is `to-waves`'s job, run once the Program-PRD exists).

package/README.md

@@ -332,6 +332,21 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.16.1
+
+- changed: `.agents/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/to-prd/SKILL.md`
+- changed: `.claude/hooks/drift-guard.py`
+- changed: `.claude/skills/kit-update/SKILL.md`
+- changed: `.claude/skills/to-prd/SKILL.md`
+
+### 0.16.0
+
+- added: `.agents/skills/setup-workflow/census.md`
+- added: `.claude/skills/setup-workflow/census.md`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
 ### 0.15.0
 
 - added: `.agents/skills/census-update/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.15.0",
+  "kitVersion": "0.16.1",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -339,7 +339,7 @@
       "kind": "skill",
       "ownerSkill": "kit-update",
       "surface": "codex",
-      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
+      "sha256": "5b7a8c11b5852ee115fa8d3f66a3938d7b4db173a47d711da48abab635b2c261",
       "mode": 420,
       "origin": "kit"
     },
@@ -487,6 +487,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/census.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "ec80f4ad36073e0c7c903434fa098d24f31b9d9a46ce55623782173ddba2e5f9",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/code-review.md",
       "kind": "skill",
@@ -546,7 +555,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
+      "sha256": "91ba30cc08206204c83d189274579471366221ccfe8f2abdf36957ad85ae136b",
       "mode": 420,
       "origin": "kit"
     },
@@ -708,7 +717,7 @@
       "kind": "skill",
       "ownerSkill": "to-prd",
       "surface": "codex",
-      "sha256": "f626fd0f451dd49d14d1d075da787f075853810926c1ace54ffa19152e3d5799",
+      "sha256": "0c7c556dfae2641a452ba5874e2e977b3e6f33d941b40be93b5009cb1d959ff8",
       "mode": 420,
       "origin": "kit"
     },
@@ -848,7 +857,7 @@
     {
       "path": ".claude/hooks/drift-guard.py",
       "kind": "hook",
-      "sha256": "7497ef4bf0ab7acd681510083d10ad79753254bc6f3d435e86d529e2abc61ef3",
+      "sha256": "8a031ff04b7aa11ac7c4713de10634e1d1521ca9fbb82fc458a86f78f6d7d1cf",
       "mode": 493,
       "origin": "kit"
     },
@@ -1312,7 +1321,7 @@
       "kind": "skill",
       "ownerSkill": "kit-update",
       "surface": "claude",
-      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
+      "sha256": "5b7a8c11b5852ee115fa8d3f66a3938d7b4db173a47d711da48abab635b2c261",
       "mode": 420,
       "origin": "kit"
     },
@@ -1478,6 +1487,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/census.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "ec80f4ad36073e0c7c903434fa098d24f31b9d9a46ce55623782173ddba2e5f9",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/code-review.md",
       "kind": "skill",
@@ -1537,7 +1555,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
+      "sha256": "91ba30cc08206204c83d189274579471366221ccfe8f2abdf36957ad85ae136b",
       "mode": 420,
       "origin": "kit"
     },
@@ -1699,7 +1717,7 @@
       "kind": "skill",
       "ownerSkill": "to-prd",
       "surface": "claude",
-      "sha256": "b9e185d590853296fc0779f55b9dce58aacb424949409905e61f5758532c5009",
+      "sha256": "38352d6e792114cc6c2352c34af841033ccaf06cf34e9ccab1bc76b51a0ca4a1",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "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": {