@ikon85/agent-workflow-kit 0.16.1 → 0.16.3

package/.agents/skills/grill-me/SKILL.md

@@ -38,6 +38,10 @@ Is the change **cross-cutting** (a new pattern OR a new data structure/domain di
 
 Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
 
+### Census preflight before plan-lock
+
+For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.
+
 ## Plan-lock — writing PLAN.md
 
 Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)

package/.agents/skills/grill-with-docs/SKILL.md

@@ -16,6 +16,10 @@ Do not enact the plan until I confirm we have reached a shared understanding.
 
 </what-to-do>
 
+### Census preflight before plan-lock
+
+For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.
+
 ## Related skills
 
 **No codebase/`CONTEXT.md` present, or a simpler case?** → `grill-me` is enough — same grill without the docs layer (CONTEXT.md/ADRs).

package/.claude/skills/grill-me/SKILL.md

@@ -38,6 +38,10 @@ Is the change **cross-cutting** (a new pattern OR a new data structure/domain di
 
 Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
 
+### Census preflight before plan-lock
+
+For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.
+
 ## Plan-lock — writing PLAN.md
 
 Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)

package/.claude/skills/grill-me-codex/SKILL.md

@@ -35,6 +35,10 @@ Is the change **cross-cutting** (a new pattern OR a new data structure/domain di
 
 Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
 
+### Census preflight before plan-lock
+
+For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.
+
 When the decision tree is resolved and we're aligned, **write the agreed plan to `PLAN.md`** in this structure, then move to Act 2:
 
 > **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and run Codex from there (`-C <dir>` on the round-1 `exec`; `exec resume` rejects both `-C` and `-s`, so run resume from that cwd and force read-only via `-c sandbox_mode="read-only"`). A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.

package/.claude/skills/grill-with-docs/SKILL.md

@@ -16,6 +16,10 @@ Do not enact the plan until I confirm we have reached a shared understanding.
 
 </what-to-do>
 
+### Census preflight before plan-lock
+
+For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.
+
 ## Related skills
 
 **No codebase/`CONTEXT.md` present, or a simpler case?** → `grill-me` is enough — same grill without the docs layer (CONTEXT.md/ADRs).

package/.claude/skills/grill-with-docs-codex/SKILL.md

@@ -117,6 +117,10 @@ Is the change **cross-cutting** (a new pattern OR a new data structure/domain di
 
 Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
 
+### Census preflight before plan-lock
+
+For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.
+
 ### Handoff to Act 2
 
 When the decision tree is resolved, the glossary/ADRs are updated, and we're aligned, **write the agreed plan to `PLAN.md`** (use the canonical terms from `CONTEXT.md`), then run Act 2:

package/README.md

@@ -332,6 +332,19 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.16.3
+
+- changed: `.agents/skills/grill-me/SKILL.md`
+- changed: `.agents/skills/grill-with-docs/SKILL.md`
+- changed: `.claude/skills/grill-me-codex/SKILL.md`
+- changed: `.claude/skills/grill-me/SKILL.md`
+- changed: `.claude/skills/grill-with-docs-codex/SKILL.md`
+- changed: `.claude/skills/grill-with-docs/SKILL.md`
+
+### 0.16.2
+
+- Metadata-only release.
+
 ### 0.16.1
 
 - changed: `.agents/skills/kit-update/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.16.1",
+  "kitVersion": "0.16.3",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -186,7 +186,7 @@
       "kind": "skill",
       "ownerSkill": "grill-me",
       "surface": "codex",
-      "sha256": "f50458c12f3d87d060495ff83c8950d81d1918d537eccfabbec8762f1982353b",
+      "sha256": "132cb0e6bf3e1b5b71575f4d2707880c7ffb844ccfa2c71a80270f891d04b724",
       "mode": 420,
       "origin": "kit"
     },
@@ -222,7 +222,7 @@
       "kind": "skill",
       "ownerSkill": "grill-with-docs",
       "surface": "codex",
-      "sha256": "aebf5b7456ecc80d9c1d2e7ab611b736ed949bf5c464549bb462ca37b883e4c7",
+      "sha256": "06a68913f904ce9bb1b21c86f146a6738b401da07eb57fb3c97a4eec00b58de6",
       "mode": 420,
       "origin": "kit"
     },
@@ -1114,7 +1114,7 @@
       "kind": "skill",
       "ownerSkill": "grill-me-codex",
       "surface": "claude",
-      "sha256": "739a19b4bf176fb9e23479081e308941e77e207641a713f408fb6524c145b73d",
+      "sha256": "ab73dd6b147e05837082db5d5ab68ab118e51e59767a717c8b7a0262cfbd07b5",
       "mode": 420,
       "origin": "kit"
     },
@@ -1132,7 +1132,7 @@
       "kind": "skill",
       "ownerSkill": "grill-me",
       "surface": "claude",
-      "sha256": "939592b2e4dc7fec77a61dc8d08f53fd93c62d8a8883fd83aa70773a9d00b975",
+      "sha256": "01e95acd6abb396c4f4c3ec7980b79f81bbee22d45247e96f1fe130fea3f5dbe",
       "mode": 420,
       "origin": "kit"
     },
@@ -1168,7 +1168,7 @@
       "kind": "skill",
       "ownerSkill": "grill-with-docs-codex",
       "surface": "claude",
-      "sha256": "6704f3e0589f9c0527e4f02383ec7373bcf42ed159088eca331f9dcdebc22faa",
+      "sha256": "5c7635bf31a3dc575762793ae80dfe7a26498aedcf7f1ce0513822ea1ebdb100",
       "mode": 420,
       "origin": "kit"
     },
@@ -1204,7 +1204,7 @@
       "kind": "skill",
       "ownerSkill": "grill-with-docs",
       "surface": "claude",
-      "sha256": "818272989fb59221cabb83f47b6e66c3b06e33b676a04579af9c3a4c9040ec9e",
+      "sha256": "6250d2e64ba1248bbd40dd0c7018ab432eda4010ebc34f6c9eccefd514a1f22b",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "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": {
@@ -19,6 +19,7 @@
   },
   "files": [
     ".claude/",
+    "!.claude/logs/",
     ".agents/",
     "scripts/",
     "docs/",

package/scripts/build-kit.test.mjs

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -48,19 +48,35 @@ test('current build is self-contained and never reaches into a consumer checkout
   assert.doesNotMatch(source, /testreporter|tools\/agent-workflow-kit/);
 });
 
-test('npm pack keeps the complete scripts tree but excludes Python caches', () => {
-  const output = execFileSync('npm', ['pack', '--dry-run', '--json'], {
-    cwd: REPO, encoding: 'utf8',
-  });
-  const files = JSON.parse(output)[0].files.map((file) => file.path);
-  assert.ok(files.includes('scripts/build-kit.mjs'));
-  assert.ok(files.includes('scripts/board-sync.py'));
-  assert.ok(files.includes('scripts/kit-update-pr.mjs'));
-  assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
-  const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {
-    cwd: REPO, encoding: 'utf8',
-  }));
-  assert.ok(pkg.files.includes('scripts/'), 'package must ship future script file types');
+test('npm pack keeps product files but excludes runtime residue', async () => {
+  const logsDir = join(REPO, '.claude/logs');
+  await mkdir(logsDir, { recursive: true });
+  const ownedLogDir = await mkdtemp(join(logsDir, 'pack-runtime-'));
+  const runtimeLog = join(ownedLogDir, 'drift-guard.log');
+  const sentinelLog = join(ownedLogDir, 'preexisting.log');
+  const sentinelBytes = 'preexisting runtime log bytes\n';
+  await writeFile(sentinelLog, sentinelBytes);
+  await writeFile(runtimeLog, `${new Date().toISOString()} runtime-only\n`);
+  try {
+    const output = execFileSync('npm', ['pack', '--dry-run', '--json'], {
+      cwd: REPO, encoding: 'utf8',
+    });
+    const files = JSON.parse(output)[0].files.map((file) => file.path);
+    assert.ok(files.includes('scripts/build-kit.mjs'));
+    assert.ok(files.includes('scripts/board-sync.py'));
+    assert.ok(files.includes('scripts/kit-update-pr.mjs'));
+    assert.ok(files.includes('.claude/hooks/drift-guard.py'));
+    assert.ok(files.includes('.claude/skills/tdd/SKILL.md'));
+    assert.ok(files.every((path) => !path.startsWith('.claude/logs/')));
+    assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
+    const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {
+      cwd: REPO, encoding: 'utf8',
+    }));
+    assert.ok(pkg.files.includes('scripts/'), 'package must ship future script file types');
+    assert.equal(await readFile(sentinelLog, 'utf8'), sentinelBytes);
+  } finally {
+    await rm(ownedLogDir, { recursive: true, force: true });
+  }
 });
 
 test('packed scoped artifact keeps the existing npx default-bin inference', async () => {

package/scripts/grill-census-wiring-guard.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { access, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const CENSUS_PREFLIGHT_INVOCATION =
+  'python3 .claude/hooks/drift-guard.py --census-status';
+export const CENSUS_PREFLIGHT_CONTRACT =
+  'For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-status` before locking it. When an activated census reports `block_handoff: true` (including stale or open surfaces), stop the lock, run `$census-update`, resolve the findings, and retry. When the census is disabled or not activated, keep the status visible and perform the existing manual surface walk; do not replace that walk with census guesses.';
+
+const GRILL_FAMILY_NAME = /^grill-/;
+const SURFACE_TREES = { claude: '.claude', codex: '.agents' };
+const LOCAL_CENSUS_LOGIC = /\b(?:scanCensus|diffCensus|fingerprintCensus|resolveCensusState|activateCensus)\s*\(/;
+
+async function exists(path) {
+  try {
+    await access(path, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function auditGrillCensusWiring(repoRoot) {
+  const manifestPath = join(repoRoot, '.claude', 'skills', 'skill-manifest.json');
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const entries = Object.entries(manifest.skills ?? {})
+    .filter(([name]) => GRILL_FAMILY_NAME.test(name));
+  const problems = [];
+  const physical = [];
+
+  for (const [name, entry] of entries) {
+    if (!Array.isArray(entry.surfaces) || entry.surfaces.length === 0) {
+      problems.push(`manifest grill has no surfaces: ${name}`);
+      continue;
+    }
+    for (const surface of entry.surfaces) {
+      const tree = SURFACE_TREES[surface];
+      if (!tree) {
+        problems.push(`manifest names an unknown surface for ${name}: ${surface}`);
+        continue;
+      }
+      const path = join(repoRoot, tree, 'skills', name, 'SKILL.md');
+      physical.push({ name, surface, path });
+      if (!(await exists(path))) {
+        problems.push(`manifest surface has no skill file: ${surface}:${name}`);
+        continue;
+      }
+      const prose = await readFile(path, 'utf8');
+      const invocationCount = prose.split(CENSUS_PREFLIGHT_INVOCATION).length - 1;
+      if (invocationCount !== 1) {
+        problems.push(
+          invocationCount === 0
+            ? `missing census preflight invocation: ${surface}:${name}`
+            : `duplicate census preflight invocation: ${surface}:${name}`,
+        );
+      }
+      if (!prose.includes(CENSUS_PREFLIGHT_CONTRACT)) {
+        problems.push(`census preflight contract drifted: ${surface}:${name}`);
+      }
+      if (LOCAL_CENSUS_LOGIC.test(prose)) {
+        problems.push(`grill duplicates census engine logic: ${surface}:${name}`);
+      }
+    }
+  }
+
+  return {
+    counts: { logical: entries.length, physical: physical.length },
+    problems,
+  };
+}
+
+async function main() {
+  const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+  const result = await auditGrillCensusWiring(repoRoot);
+  console.log(`grill census wiring: ${result.counts.logical} logical, ${result.counts.physical} physical`);
+  if (result.problems.length > 0) {
+    for (const problem of result.problems) console.error(`- ${problem}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  await main();
+}

package/scripts/grill-census-wiring-guard.test.mjs

@@ -0,0 +1,107 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import {
+  CENSUS_PREFLIGHT_CONTRACT,
+  auditGrillCensusWiring,
+} from './grill-census-wiring-guard.mjs';
+
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+const realManifest = JSON.parse(await readFile(
+  join(REPO, '.claude', 'skills', 'skill-manifest.json'),
+  'utf8',
+)).skills;
+const baselineGrills = Object.fromEntries(
+  Object.entries(realManifest).filter(([name]) => name.startsWith('grill-')),
+);
+const baselineCounts = {
+  logical: Object.keys(baselineGrills).length,
+  physical: Object.values(baselineGrills)
+    .reduce((count, entry) => count + entry.surfaces.length, 0),
+};
+const [baselineName, baselineEntry] = Object.entries(baselineGrills)[0];
+const baselineSurface = baselineEntry.surfaces[0];
+let extraGrillName = 'grill-fixture-extra';
+while (extraGrillName in baselineGrills) extraGrillName += '-next';
+
+async function fixture({ manifest = baselineGrills, omitInvocation, omitFile } = {}) {
+  const root = await mkdtemp(join(tmpdir(), 'grill-census-guard-'));
+  await mkdir(join(root, '.claude', 'skills'), { recursive: true });
+  await writeFile(
+    join(root, '.claude', 'skills', 'skill-manifest.json'),
+    `${JSON.stringify({ skills: manifest })}\n`,
+  );
+  for (const [name, entry] of Object.entries(manifest)) {
+    for (const surface of entry.surfaces) {
+      const relative = `${surface}:${name}`;
+      if (relative === omitFile) continue;
+      const tree = surface === 'claude' ? '.claude' : '.agents';
+      const directory = join(root, tree, 'skills', name);
+      await mkdir(directory, { recursive: true });
+      const invocation = relative === omitInvocation ? '' : CENSUS_PREFLIGHT_CONTRACT;
+      await writeFile(join(directory, 'SKILL.md'), `# ${name}\n${invocation}\n`);
+    }
+  }
+  return root;
+}
+
+test('fixture wiring covers every grill and surface in the real manifest', async () => {
+  const result = await auditGrillCensusWiring(await fixture());
+
+  assert.deepEqual(result.counts, baselineCounts);
+  assert.deepEqual(result.problems, []);
+});
+
+test('a grill surface missing the shared preflight invocation is rejected', async () => {
+  const result = await auditGrillCensusWiring(await fixture({
+    omitInvocation: `${baselineSurface}:${baselineName}`,
+  }));
+
+  assert.match(
+    result.problems.join('\n'),
+    new RegExp(`missing census preflight invocation.*${baselineName}`, 'i'),
+  );
+});
+
+test('a dead manifest surface reference is rejected', async () => {
+  const result = await auditGrillCensusWiring(await fixture({
+    omitFile: `${baselineSurface}:${baselineName}`,
+  }));
+
+  assert.match(
+    result.problems.join('\n'),
+    new RegExp(`manifest surface has no skill file.*${baselineName}`, 'i'),
+  );
+});
+
+test('a newly manifested grill variant expands the family and cannot hide a missing surface', async () => {
+  const addedSurfaces = ['claude', 'codex'];
+  const manifest = {
+    ...baselineGrills,
+    [extraGrillName]: { surfaces: addedSurfaces },
+  };
+  const result = await auditGrillCensusWiring(await fixture({
+    manifest,
+    omitFile: `codex:${extraGrillName}`,
+  }));
+
+  assert.deepEqual(result.counts, {
+    logical: baselineCounts.logical + 1,
+    physical: baselineCounts.physical + addedSurfaces.length,
+  });
+  assert.match(
+    result.problems.join('\n'),
+    new RegExp(`manifest surface has no skill file.*${extraGrillName}`, 'i'),
+  );
+});
+
+test('the repository wiring covers the complete manifest-derived grill family', async () => {
+  const result = await auditGrillCensusWiring(REPO);
+
+  assert.deepEqual(result.counts, baselineCounts);
+  assert.deepEqual(result.problems, []);
+});

package/.claude/logs/drift-guard.log

@@ -1,3 +0,0 @@
-2026-07-15T18:45:54 census state=failed reasons=["target repository unavailable (Command '['git', '-C', '/tmp/repo', 'rev-parse', '--show-toplevel']' returned non-zero exit status 128.)"]
-2026-07-15T18:45:55 census state=failed reasons=['target repository unavailable (handoff target repository containment check failed)']
-2026-07-15T18:45:59 census state=failed reasons=['scan']