@ikon85/agent-workflow-kit 0.15.0 → 0.16.1

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

@@ -44,6 +44,19 @@ the matching GitHub release contain the same artifact.
    resume the transaction through the update API's `resumeFrom` option. Do not
    copy staged files into the consumer by hand.
 
+5. Check the optional project census after the update:
+
+   ```sh
+   python3 .claude/hooks/drift-guard.py --census-status
+   ```
+
+   When the report names a newer census builder or `refresh_required`, advise
+   the user to run `$census-update`. The kit updater must never overwrite a
+   consumer-owned census, profile, local scanner, decision, or override. A
+   missing, disabled, unactivated, or temporarily unavailable census remains a
+   visible manual-walk condition and does not invalidate an otherwise verified
+   kit update.
+
 ## State contract
 
 The update API reports `checking -> preview/awaiting_decision -> staging ->

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/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).