@ikon85/agent-workflow-kit 0.12.0 → 0.14.0

package/scripts/census/scan.mjs

@@ -0,0 +1,174 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fingerprintCensus, sha256 } from './fingerprint.mjs';
+import { CENSUS_VERDICTS, resolveCensusState } from './state.mjs';
+
+const exec = promisify(execFile);
+const EVIDENCE_PARTS = new Set(['docs', 'test', 'tests', '__tests__']);
+const EXCLUDED_PARTS = new Set([
+  '.git', '.next', 'build', 'coverage', 'dist', 'generated', 'node_modules', 'vendor',
+]);
+const CONFIG_NAMES = new Set([
+  'package.json', 'tsconfig.json', 'vite.config.js', 'vite.config.mjs',
+  'vite.config.ts', 'next.config.js', 'next.config.mjs', 'Dockerfile',
+]);
+
+function pathParts(path) {
+  return path.split('/');
+}
+
+function isEvidence(path) {
+  const parts = pathParts(path);
+  return parts.some((part) => EVIDENCE_PARTS.has(part))
+    || /(?:^|\.)test\.[^.]+$/.test(path)
+    || /(?:^|\.)spec\.[^.]+$/.test(path)
+    || /(?:^|\/)README(?:\.[^/]*)?$/.test(path);
+}
+
+function isSecret(path) {
+  return pathParts(path).some((part) => {
+    const name = part.toLowerCase();
+    return name === '.env' || name.startsWith('.env.')
+      || /^(?:secrets?|credentials?)(?:[._-]|$)/.test(name)
+      || /private[-_.]?key/.test(name);
+  });
+}
+
+function isExcluded(path) {
+  return pathParts(path).some((part) => EXCLUDED_PARTS.has(part));
+}
+
+function isProduct(path) {
+  const parts = pathParts(path);
+  if (CONFIG_NAMES.has(parts.at(-1))) return true;
+  return parts.some((part) => ['src', 'app', 'apps', 'lib', 'packages'].includes(part));
+}
+
+function familyFor(path, kind) {
+  if (kind === 'config') return 'production-config';
+  const parts = pathParts(path);
+  const rootIndex = parts.findIndex((part) => ['src', 'app', 'apps', 'lib', 'packages'].includes(part));
+  const packageRoot = ['apps', 'packages'].includes(parts[rootIndex]);
+  return parts.slice(0, Math.min(rootIndex + (packageRoot ? 2 : 1), parts.length)).join('/');
+}
+
+async function gitPaths(repoRoot, args) {
+  const { stdout } = await exec('git', args, { cwd: repoRoot, encoding: 'utf8' });
+  return stdout.split('\0').filter(Boolean).sort();
+}
+
+async function gitIgnoredPaths(repoRoot, paths) {
+  if (!paths.length) return new Set();
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', ['check-ignore', '--no-index', '-z', '--stdin'], { cwd: repoRoot });
+    const chunks = [];
+    child.stdout.on('data', (chunk) => chunks.push(chunk));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0 && code !== 1) return reject(new Error(`git check-ignore exited ${code}`));
+      resolve(new Set(Buffer.concat(chunks).toString('utf8').split('\0').filter(Boolean)));
+    });
+    child.stdin.end(`${paths.join('\0')}\0`);
+  });
+}
+
+async function regularContainedPath(repoRoot, realRepoRoot, path) {
+  const candidate = resolve(repoRoot, path);
+  const lexicalRelative = relative(resolve(repoRoot), candidate);
+  if (lexicalRelative === '..' || lexicalRelative.startsWith(`..${sep}`) || isAbsolute(lexicalRelative)) {
+    return null;
+  }
+  let stats;
+  let canonical;
+  try {
+    stats = await lstat(candidate);
+    // Symlinks, including links that resolve inside the repository, are excluded.
+    // Only a regular file whose canonical path remains inside the repository may be read.
+    if (!stats.isFile()) return null;
+    canonical = await realpath(candidate);
+  } catch {
+    return null;
+  }
+  const canonicalRelative = relative(realRepoRoot, canonical);
+  if (canonicalRelative === '..' || canonicalRelative.startsWith(`..${sep}`) || isAbsolute(canonicalRelative)) {
+    return null;
+  }
+  return candidate;
+}
+
+function behaviorSummary(entries) {
+  const verdicts = new Set(Object.values(CENSUS_VERDICTS));
+  return entries.map(({ name, status }) => {
+    if (typeof name !== 'string' || !name) throw new TypeError('behavior family requires a name');
+    if (!verdicts.has(status)) throw new TypeError(`invalid behavior family verdict: ${status}`);
+    return { name, status, type: 'behavior' };
+  }).sort((left, right) => {
+    const leftKey = `${left.name}\0${left.status}`;
+    const rightKey = `${right.name}\0${right.status}`;
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+}
+
+function surfaceSummary(entries, openPaths) {
+  const statuses = new Map(entries.map(({ family }) => [family, CENSUS_VERDICTS.covered]));
+  for (const path of openPaths) {
+    if (isProduct(path) && !isExcluded(path) && !isSecret(path)) {
+      const kind = CONFIG_NAMES.has(pathParts(path).at(-1)) ? 'config' : 'source';
+      statuses.set(familyFor(path, kind), CENSUS_VERDICTS.open);
+    }
+  }
+  return [...statuses].sort(([left], [right]) => (
+    left < right ? -1 : left > right ? 1 : 0
+  )).map(([name, status]) => ({
+    name, status, type: 'surface',
+  }));
+}
+
+export async function scanCensus({
+  repoRoot,
+  behaviorFamilies = [],
+  enabled = false,
+  hasActive = false,
+  readText = (path) => readFile(path, 'utf8'),
+}) {
+  const realRepoRoot = await realpath(repoRoot);
+  const tracked = await gitPaths(repoRoot, ['ls-files', '-z']);
+  const untracked = await gitPaths(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z']);
+  const ignored = await gitIgnoredPaths(repoRoot, tracked);
+  const denominator = [];
+  const evidence = [];
+  const openPaths = [...untracked];
+  for (const path of tracked) {
+    if (ignored.has(path) || isSecret(path) || isExcluded(path)) continue;
+    const target = isEvidence(path) ? evidence : isProduct(path) ? denominator : null;
+    if (!target) continue;
+    const readablePath = await regularContainedPath(repoRoot, realRepoRoot, path);
+    if (!readablePath) {
+      if (target === denominator) openPaths.push(path);
+      continue;
+    }
+    let content;
+    try {
+      content = await readText(readablePath);
+    } catch {
+      if (target === denominator) openPaths.push(path);
+      continue;
+    }
+    const kind = CONFIG_NAMES.has(pathParts(path).at(-1)) ? 'config' : 'source';
+    target.push({ family: familyFor(path, kind), hash: sha256(content), kind, path });
+  }
+  const families = {
+    surfaces: surfaceSummary(denominator, openPaths),
+    behaviors: behaviorSummary(behaviorFamilies),
+  };
+  const result = { denominator, evidence, families };
+  const hasOpen = [...families.surfaces, ...families.behaviors]
+    .some(({ status }) => status === CENSUS_VERDICTS.open);
+  return {
+    ...result,
+    fingerprints: fingerprintCensus(result),
+    state: resolveCensusState({ enabled, hasActive, hasOpen }),
+  };
+}

package/scripts/census/state.mjs

@@ -0,0 +1,23 @@
+export const CENSUS_STATES = Object.freeze([
+  'disabled',
+  'bootstrap',
+  'current',
+  'refresh_required',
+  'updating',
+  'failed',
+]);
+
+export const CENSUS_VERDICTS = Object.freeze({
+  covered: 'abgedeckt',
+  notRelevant: 'nicht relevant',
+  open: 'offen',
+});
+
+export function resolveCensusState({ enabled, hasActive, hasOpen = false, updating = false, failed = false }) {
+  if (!enabled) return 'disabled';
+  if (updating) return 'updating';
+  if (failed) return 'failed';
+  if (!hasActive) return 'bootstrap';
+  if (hasOpen) return 'refresh_required';
+  return 'current';
+}

package/scripts/census/state.test.mjs

@@ -0,0 +1,15 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CENSUS_STATES, resolveCensusState } from './index.mjs';
+
+test('state resolver implements the complete census state contract', () => {
+  assert.deepEqual(CENSUS_STATES, [
+    'disabled', 'bootstrap', 'current', 'refresh_required', 'updating', 'failed',
+  ]);
+  assert.equal(resolveCensusState({ enabled: false }), 'disabled');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: false }), 'bootstrap');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true }), 'current');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true, hasOpen: true }), 'refresh_required');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true, updating: true }), 'updating');
+  assert.equal(resolveCensusState({ enabled: true, hasActive: true, failed: true }), 'failed');
+});

package/scripts/census/transaction.mjs

@@ -0,0 +1,50 @@
+import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export class CensusTransactionError extends Error {
+  constructor(message, state, cause) {
+    super(message, { cause });
+    this.name = 'CensusTransactionError';
+    this.state = state;
+  }
+}
+async function acquireLock(lockPath) {
+  await mkdir(dirname(lockPath), { recursive: true });
+  try {
+    const handle = await open(lockPath, 'wx');
+    await handle.close();
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      throw new CensusTransactionError(`census update already locked: ${lockPath}`, 'updating', error);
+    }
+    throw error;
+  }
+}
+
+/** Stage, verify, then atomically replace the active census while holding a local lock. */
+export async function activateCensus({
+  activePath,
+  candidate,
+  verify,
+  lockPath = `${activePath}.lock`,
+  stagePath = `${activePath}.candidate`,
+  renameCandidate = rename,
+}) {
+  if (typeof verify !== 'function') {
+    throw new TypeError('census activation requires a callable verifier');
+  }
+  await acquireLock(lockPath);
+  try {
+    const serialized = `${JSON.stringify(candidate)}\n`;
+    await writeFile(stagePath, serialized, 'utf8');
+    const verified = await verify(candidate, { activePath, stagePath });
+    if (verified === false) throw new Error('census candidate verification returned false');
+    await renameCandidate(stagePath, activePath);
+    return { activePath, state: 'current' };
+  } catch (error) {
+    await rm(stagePath, { force: true });
+    throw new CensusTransactionError(`census activation failed: ${error.message}`, 'failed', error);
+  } finally {
+    await rm(lockPath, { force: true });
+  }
+}

package/scripts/census/transaction.test.mjs

@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { activateCensus } from './index.mjs';
+
+test('activation requires a callable verifier before staging or swapping', async () => {
+  for (const verify of [undefined, 'not-callable']) {
+    const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+    const activePath = join(root, 'active.json');
+    const previous = '{"generation":"previous"}\n';
+    await writeFile(activePath, previous);
+    let swapped = false;
+    try {
+      await assert.rejects(
+        activateCensus({
+          activePath,
+          candidate: { generation: 'next' },
+          renameCandidate: async () => { swapped = true; },
+          verify,
+        }),
+        /callable verifier/,
+      );
+      assert.equal(await readFile(activePath, 'utf8'), previous);
+      await assert.rejects(readFile(`${activePath}.candidate`), { code: 'ENOENT' });
+      await assert.rejects(readFile(`${activePath}.lock`), { code: 'ENOENT' });
+      assert.equal(swapped, false);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+});
+
+test('verify failure preserves active bytes and a second run can succeed', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+  const activePath = join(root, 'active.json');
+  const previous = '{"generation":"previous"}\n';
+  await writeFile(activePath, previous);
+  try {
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate: { generation: 'next' },
+        verify: async () => { throw new Error('fixture verify failure'); },
+      }),
+      (error) => error.state === 'failed',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+
+    const result = await activateCensus({
+      activePath,
+      candidate: { generation: 'next' },
+      verify: async ({ generation }) => generation === 'next',
+    });
+    assert.equal(result.state, 'current');
+    assert.equal(await readFile(activePath, 'utf8'), '{"generation":"next"}\n');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('swap failure preserves active bytes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+  const activePath = join(root, 'active.json');
+  const previous = '{"generation":"previous"}\n';
+  await writeFile(activePath, previous);
+  try {
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate: { generation: 'next' },
+        renameCandidate: async () => { throw new Error('fixture swap failure'); },
+        verify: async () => true,
+      }),
+      (error) => error.state === 'failed',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('an existing local lock reports updating without touching active bytes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'awk-census-transaction-'));
+  const activePath = join(root, 'active.json');
+  const previous = '{"generation":"previous"}\n';
+  await writeFile(activePath, previous);
+  await writeFile(`${activePath}.lock`, 'held\n');
+  try {
+    await assert.rejects(
+      activateCensus({
+        activePath,
+        candidate: { generation: 'next' },
+        verify: async () => true,
+      }),
+      (error) => error.state === 'updating',
+    );
+    assert.equal(await readFile(activePath, 'utf8'), previous);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/scripts/kit-update-pr.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { appendFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+export const UPDATE_BRANCH = 'agent-workflow-kit/update';
+export const UPDATE_TITLE = 'chore: update agent workflow kit';
+const UPDATE_BODY = [
+  'Automated, parity-verified update of `@ikon85/agent-workflow-kit`.',
+  '',
+  'The transactional update candidate passed the consumer test suite before this branch was published.',
+  '',
+  'This pull request is never merged automatically.',
+].join('\n');
+const exec = promisify(execFile);
+
+export async function orchestrateUpdatePullRequest(options) {
+  const {
+    runUpdate, hasChanges, listPullRequests, publishBranch,
+    createPullRequest, updatePullRequest, branch = UPDATE_BRANCH,
+  } = options;
+  const update = await runUpdate();
+  if (update.exitCode !== 0) {
+    return { status: update.exitCode === 2 ? 'conflicted' : 'failed', branch, update };
+  }
+  if (!await hasChanges()) return { status: 'current', branch };
+
+  const pulls = await listPullRequests(branch);
+  if (pulls.length > 1) {
+    return { status: 'failed', branch, reason: 'multiple-open-pull-requests' };
+  }
+  await publishBranch(branch);
+  const input = { title: UPDATE_TITLE, body: UPDATE_BODY, branch };
+  if (pulls.length === 1) {
+    await updatePullRequest(pulls[0].number, input);
+    return { status: 'updated', branch, pullRequest: pulls[0].number };
+  }
+  await createPullRequest(input);
+  return { status: 'created', branch };
+}
+
+export function createSystemAdapters({
+  cwd = process.cwd(), env = process.env, execute = exec,
+} = {}) {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const command = async (file, args) => {
+    try {
+      const result = await execute(file, args, { cwd, env, encoding: 'utf8' });
+      return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+    } catch (error) {
+      if (typeof error.code !== 'number') throw error;
+      return { exitCode: error.code, stdout: error.stdout || '', stderr: error.stderr || '' };
+    }
+  };
+  const checked = async (file, args) => {
+    const result = await command(file, args);
+    if (result.exitCode !== 0) throw new Error(result.stderr || `${file} exited ${result.exitCode}`);
+    return result.stdout.trim();
+  };
+
+  return {
+    runUpdate: () => command(process.execPath, [join(packageRoot, 'src/cli.mjs'), 'update', '--yes']),
+    hasChanges: async () => Boolean(await checked('git', ['status', '--porcelain', '--untracked-files=all'])),
+    listPullRequests: async (branch) => JSON.parse(await checked('gh', [
+      'pr', 'list', '--state', 'open', '--head', branch, '--json', 'number,url',
+    ]) || '[]'),
+    publishBranch: async (branch) => {
+      await checked('git', ['config', 'user.name', 'agent-workflow-kit[bot]']);
+      await checked('git', ['config', 'user.email', 'agent-workflow-kit[bot]@users.noreply.github.com']);
+      await checked('git', ['add', '--all']);
+      await checked('git', ['commit', '-m', UPDATE_TITLE]);
+      const remote = await checked('git', ['ls-remote', 'origin', `refs/heads/${branch}`]);
+      const expected = remote.split(/\s+/)[0] || '';
+      await checked('git', [
+        'push', `--force-with-lease=refs/heads/${branch}:${expected}`,
+        'origin', `HEAD:refs/heads/${branch}`,
+      ]);
+    },
+    createPullRequest: ({ title, body, branch }) => checked('gh', [
+      'pr', 'create', '--head', branch, '--title', title, '--body', body,
+    ]),
+    updatePullRequest: (number, { title, body }) => checked('gh', [
+      'pr', 'edit', String(number), '--title', title, '--body', body,
+    ]),
+  };
+}
+
+export async function runCli(options = {}) {
+  let report;
+  try {
+    report = await orchestrateUpdatePullRequest(createSystemAdapters(options));
+  } catch (error) {
+    report = { status: 'failed', branch: UPDATE_BRANCH, reason: error.message };
+  }
+  const rendered = `${JSON.stringify(report, null, 2)}\n`;
+  process.stdout.write(rendered);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    await appendFile(process.env.GITHUB_STEP_SUMMARY, `## Agent Workflow Kit update\n\n\`\`\`json\n${rendered}\`\`\`\n`);
+  }
+  if (report.status === 'conflicted') process.exitCode = 2;
+  else if (report.status === 'failed') process.exitCode = 1;
+  return report;
+}
+
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--help') || process.argv.includes('-h') || process.argv.includes('help')) {
+    process.stdout.write('Usage: agent-workflow-kit-update-pr\n');
+  } else {
+    await runCli();
+  }
+}

package/scripts/kit-update-pr.test.mjs

@@ -0,0 +1,99 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createSystemAdapters, orchestrateUpdatePullRequest } from './kit-update-pr.mjs';
+
+function harness({ update = { exitCode: 0 }, changed = true, pulls = [] } = {}) {
+  const calls = [];
+  return {
+    calls,
+    options: {
+      runUpdate: async () => (calls.push('update'), update),
+      hasChanges: async () => (calls.push('changes'), changed),
+      listPullRequests: async (branch) => (calls.push(['list', branch]), pulls),
+      publishBranch: async (branch) => calls.push(['publish', branch]),
+      createPullRequest: async (input) => calls.push(['create', input]),
+      updatePullRequest: async (number, input) => calls.push(['upsert', number, input]),
+    },
+  };
+}
+
+test('a successful update creates one stable update pull request', async () => {
+  const h = harness();
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'created');
+  assert.equal(report.branch, 'agent-workflow-kit/update');
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list', 'publish', 'create',
+  ]);
+});
+
+test('a conflict produces a structured report without touching the stable branch', async () => {
+  const h = harness({ update: { exitCode: 2, stdout: 'conflicts: 1', stderr: '' } });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.deepEqual(report, {
+    status: 'conflicted',
+    branch: 'agent-workflow-kit/update',
+    update: { exitCode: 2, stdout: 'conflicts: 1', stderr: '' },
+  });
+  assert.deepEqual(h.calls, ['update']);
+});
+
+test('a release mismatch fails without touching the consumer update branch', async () => {
+  const h = harness({ update: { exitCode: 1, stdout: '', stderr: 'release mismatch' } });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'failed');
+  assert.equal(report.update.stderr, 'release mismatch');
+  assert.deepEqual(h.calls, ['update']);
+});
+
+test('ambiguous existing pull requests fail before the last good branch is changed', async () => {
+  const h = harness({ pulls: [{ number: 7 }, { number: 9 }] });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'failed');
+  assert.equal(report.reason, 'multiple-open-pull-requests');
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list',
+  ]);
+});
+
+test('an already current consumer is a no-op', async () => {
+  const h = harness({ changed: false });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'current');
+  assert.deepEqual(h.calls, ['update', 'changes']);
+});
+
+test('a repeated run updates the one existing stable pull request', async () => {
+  const h = harness({ pulls: [{ number: 7 }] });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'updated');
+  assert.equal(report.pullRequest, 7);
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list', 'publish', 'upsert',
+  ]);
+});
+
+test('publishing commits in place and lease-protects the stable remote branch', async () => {
+  const commands = [];
+  const execute = async (file, args) => {
+    commands.push([file, ...args]);
+    if (args[0] === 'ls-remote') return { stdout: 'abc123\trefs/heads/agent-workflow-kit/update\n', stderr: '' };
+    return { stdout: '', stderr: '' };
+  };
+  const adapter = createSystemAdapters({ cwd: '/consumer', env: {}, execute });
+
+  await adapter.publishBranch('agent-workflow-kit/update');
+
+  const gitCommands = commands.map((command) => command.slice(1));
+  assert.equal(gitCommands.some(([verb]) => ['switch', 'checkout', 'reset'].includes(verb)), false);
+  assert.deepEqual(gitCommands.at(-1), [
+    'push', '--force-with-lease=refs/heads/agent-workflow-kit/update:abc123',
+    'origin', 'HEAD:refs/heads/agent-workflow-kit/update',
+  ]);
+});

package/scripts/test_skill_setup_workflow_seeds.py

@@ -45,6 +45,16 @@ def classify(first_line, is_empty):
     return "create" if is_empty else "skip"
 
 
+def update_workflow_action(
+    provider, choice, destination_exists, prerequisites=True,
+    pull_requests_allowed=True,
+):
+    """Reference decision table for the prompt-driven setup contract."""
+    if provider != "github" or destination_exists or choice != "enable":
+        return "skip"
+    return "create" if prerequisites and pull_requests_allowed else "skip"
+
+
 class IdempotencyRule(unittest.TestCase):
     CASES = [
         # (first_line, is_empty, expected)
@@ -71,6 +81,61 @@ class IdempotencyRule(unittest.TestCase):
 
 
 class SeedTemplatesValid(unittest.TestCase):
+    def test_update_workflow_provider_and_choice_fixtures(self):
+        fixtures = [
+            ("github", "enable", False, True, True, "create"),
+            ("github", "opt-out", False, True, True, "skip"),
+            ("github", "later", False, True, True, "skip"),
+            ("github", "enable", True, True, True, "skip"),
+            ("github", "enable", False, False, True, "skip"),
+            ("github", "enable", False, True, False, "skip"),
+            ("gitlab", "enable", False, True, True, "skip"),
+            ("local", "enable", False, True, True, "skip"),
+        ]
+        for provider, choice, exists, prerequisites, allowed, expected in fixtures:
+            self.assertEqual(
+                update_workflow_action(
+                    provider, choice, exists, prerequisites, allowed,
+                ), expected,
+            )
+
+    def test_github_update_opt_in_is_provider_aware_and_idempotent(self):
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+        for token in (
+            "Automatic Kit update pull requests",
+            ".github/workflows/agent-workflow-kit-update.yml",
+            "Opt out",
+            "Ask later",
+            "GitHub tracker",
+            "skipped (already present)",
+            "package-lock.json",
+            "npm test",
+            "can_approve_pull_request_reviews",
+            "Allow GitHub Actions to create and approve pull requests",
+            "explicit confirmation",
+        ):
+            self.assertIn(token, skill)
+        self.assertIn("do not create a GitHub workflow", skill)
+
+    def test_github_update_workflow_has_safe_triggers_and_scoped_runner(self):
+        workflow = (SKILL / "assets/agent-workflow-kit-update.yml").read_text(encoding="utf-8")
+        for token in (
+            "schedule:", "workflow_dispatch:", "contents: write",
+            "pull-requests: write", "agent-workflow-kit-update-pr",
+            "@ikon85/agent-workflow-kit@latest", "fetch-depth: 0",
+            "node-version: 22.14", "npm ci --ignore-scripts",
+        ):
+            self.assertIn(token, workflow)
+        for forbidden in ("npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge"):
+            self.assertNotIn(forbidden, workflow)
+
+        mirror = (REPO / ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml")
+        self.assertEqual(workflow, mirror.read_text(encoding="utf-8"))
+
+    def test_update_pr_runner_is_an_installed_package_binary(self):
+        package = json.loads((REPO / "package.json").read_text(encoding="utf-8"))
+        self.assertEqual(package["bin"]["agent-workflow-kit-update-pr"], "scripts/kit-update-pr.mjs")
+
     def test_spec_completeness_seed_has_valid_self_critique_block(self):
         """A convention without a valid Trigger/Check/Korrektur block makes
         spec-self-critique point 8 warn — the seed must carry one (Codex R1 #14)."""