@ikon85/agent-workflow-kit 0.10.0

package/scripts/board_config.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""board_config.py — shared loader for the board-sync profile.
+
+The planning scripts (board-sync.py / execute-ready-check.py / pr-body-check.py)
+carry NO inline board IDs. They read every board-specific value — field IDs,
+status option names, labels, branch prefixes, PR-body markers, headings — from a
+single machine-readable profile embedded in `docs/agents/board-sync.md`:
+
+    <!-- board-sync:profile -->
+    ```json
+    { "repo": "...", "project": {...}, "fields": {...}, ... }
+    ```
+
+A fenced ```json block is the SSOT (board discovery via
+`gh project field-list --format json` already emits JSON, so a fill is a paste,
+and `json` is stdlib). The human field-catalog table in the doc is documentation
+only; the IDs live solely in this block, so the two can't drift.
+
+`/setup-workflow` seeds + fills this block per consumer. Override the path with
+the `BOARD_SYNC_PROFILE` env var (tests / non-default layouts).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+# Default: <repo-root>/docs/agents/board-sync.md, resolved relative to THIS file
+# (scripts/board_config.py → parent.parent == repo root) so it works regardless
+# of the caller's cwd, in this repo and in a consumer install alike.
+_DEFAULT_PROFILE = Path(__file__).resolve().parent.parent / "docs" / "agents" / "board-sync.md"
+
+_MARKER_RE = re.compile(r"<!--\s*board-sync:profile\s*-->")
+_FENCE_RE = re.compile(r"```json\s*\n(.*?)\n```", re.DOTALL)
+
+# Required dotted paths — every value a planning script dereferences. A consumer
+# who mis-fills the profile gets a clear "missing key X" at startup, not a deep
+# KeyError mid-command.
+_REQUIRED_PATHS = (
+    ("repo",),
+    ("project", "number"), ("project", "owner"), ("project", "nodeId"),
+    ("fields", "status", "id"), ("fields", "status", "options"),
+    ("fields", "wave"), ("fields", "cluster"),
+    ("fields", "specPath"), ("fields", "planPath"),
+    ("labels", "readyForAgent"), ("labels", "typePrefix"), ("labels", "clusterType"),
+    ("labels", "waveStub"),
+    ("branchPrefixes",),
+    ("prMarkers", "partOf"), ("prMarkers", "retroMarker"), ("prMarkers", "retroValues"),
+    ("headings", "vorBau"),
+)
+
+
+class ConfigError(RuntimeError):
+    """Raised when the board profile is absent, malformed, or incomplete."""
+
+
+def _profile_path(path=None) -> Path:
+    if path is not None:
+        return Path(path)
+    env = os.environ.get("BOARD_SYNC_PROFILE")
+    return Path(env) if env else _DEFAULT_PROFILE
+
+
+def _extract_block(text: str, src: str) -> str:
+    marker = _MARKER_RE.search(text)
+    if not marker:
+        raise ConfigError(
+            f"{src}: no `<!-- board-sync:profile -->` marker found — "
+            "run /setup-workflow to seed the board profile.")
+    fence = _FENCE_RE.search(text, marker.end())
+    if not fence:
+        raise ConfigError(
+            f"{src}: the `board-sync:profile` marker is not followed by a "
+            "```json block.")
+    return fence.group(1)
+
+
+def _check_required(cfg, src: str) -> None:
+    for path in _REQUIRED_PATHS:
+        node = cfg
+        for key in path:
+            if not isinstance(node, dict) or key not in node:
+                raise ConfigError(
+                    f"{src}: profile is missing required key "
+                    f"'{'.'.join(path)}'.")
+            node = node[key]
+
+
+def load_board_config(path=None) -> dict:
+    """Parse + validate the board profile. Raises ConfigError on any problem."""
+    p = _profile_path(path)
+    if not p.exists():
+        raise ConfigError(
+            f"board profile not found at {p} — run /setup-workflow to seed "
+            "docs/agents/board-sync.md.")
+    raw = _extract_block(p.read_text(encoding="utf-8"), str(p))
+    try:
+        cfg = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(
+            f"{p}: the board-sync:profile block is not valid JSON: {exc}") from exc
+    if not isinstance(cfg, dict):
+        raise ConfigError(f"{p}: the board-sync:profile block must be a JSON object.")
+    _check_required(cfg, str(p))
+    return cfg
+
+
+# --- optional Programm-Flughöhe keys ------------------------------------------
+# `fields.phase` and `labels.programType` are deliberately NOT in _REQUIRED_PATHS
+# — Phasen are optional per the program-altitude design (§2) and a Program-PRD's
+# type label has a literal default, so an existing consumer profile without
+# either key keeps loading unchanged (no migration forced by this slice).
+def phase_field_id(cfg: dict):
+    """The `fields.phase.id` (a Projects-v2 single-select field id), or None when
+    the profile hasn't configured a Phase field yet. Callers must degrade to a
+    visible skip/hint on None, never a KeyError (mirrors `validate-graph`'s
+    existing defensive read of this same optional key)."""
+    return (cfg.get("fields", {}).get("phase") or {}).get("id")
+
+
+def program_type_label(cfg: dict) -> str:
+    """The `labels.programType` label, or the literal default `"type:program"`
+    when the profile hasn't set one — a Program-PRD's board-filterable type
+    label (the `<!-- prd: program -->` body marker is not filterable)."""
+    return cfg.get("labels", {}).get("programType", "type:program")
+
+
+# The semantic role keys of the workflow — schema, not
+# vocabulary; stable once shipped, extend additively, never rename. Single
+# home so CLI `choices`, docs, and future consumers reference one list.
+STATUS_ROLE_KEYS = ("idea", "triaged", "spec", "inProgress", "review", "done")
+
+
+def status_roles(cfg: dict) -> dict:
+    """The `fields.status.roles` map: semantic role keys (`idea`,
+    `triaged`, `spec`, `inProgress`, `review`, `done`) → this board's own
+    status option NAMES. This is where the workflow's status vocabulary lives —
+    scripts read roles, never option-name literals, so any board language works.
+
+    Optional (not in _REQUIRED_PATHS, like `fields.phase`): a profile without
+    the key returns an EMPTY DICT — deliberately no language default in code
+    (a German default would leak vocabulary into consumer installs, an English
+    one would be silently wrong for German boards). Callers degrade visibly:
+    passive paths (SessionStart hook, status-token sync) log a skip/hint;
+    explicit `--status-role` CLI calls fail loud with a migration snippet."""
+    return (cfg.get("fields", {}).get("status") or {}).get("roles") or {}

package/scripts/board_fields.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""board_fields.py — batched field-writes + a field-value read for Projects-v2
+items.
+
+Three mechanics `board-sync.py` lacked before this slice:
+
+  - `stamp-batch` — alias-batched `updateProjectV2ItemFieldValue` mutations
+    (~30 aliases/request, chunked) instead of one `gh` call per field per
+    item. `to-waves` stamps Wave+Phase on 50+ items at publish time;
+    the existing sequential `stamp_arg_list` path (still the create/add/promote
+    fallback for a single item) does not scale to that.
+  - `field-value` — read a project item's current field value for an issue.
+    Nothing in board-sync.py read a field back before this slice; `promote`'s
+    Mismatch-Guard is the first consumer.
+  - the `promote` guards themselves (pure decision functions) — Wave-Mismatch
+    and Program-PRD-Refusal — kept here alongside field-value since a guard IS
+    the read's only consumer today.
+
+PURE — no gh / no I/O. The `_gh`/`_gh_json` seam calls and CLI wiring live in
+board-sync.py (mirrors anchor_table.py's / program_graph.py's split).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+# GraphQL mutations tolerate far more than this per request (GitHub's Secondary
+# Rate Limit budgets ~5 "points"), but a hard chunk cap keeps one failed/timed-out
+# request's blast radius small and the per-alias error report readable.
+CHUNK_SIZE = 30
+
+
+@dataclass
+class FieldStamp:
+    """One (item, field) write for the batched mutation — also the unit the
+    per-alias error report and the repair command are built from."""
+    item_id: str
+    field_id: str
+    kind: str            # "number" | "single_select"
+    value: object         # the GraphQL literal value: int, or an option-id str
+    issue: int             # for the report + repair command
+    field_name: str        # "wave" | "phase" — doubles as the repair CLI flag name
+    display_value: object  # human-readable value for the repair command
+                            # (e.g. the Phase NAME, not its resolved option-id)
+
+
+def build_stamps(items: list[dict], *, wave_field_id: str,
+                  phase_cfg: Optional[dict]) -> tuple[list[FieldStamp], int]:
+    """FieldStamp list + a skipped-phase-stamp count from raw item dicts
+    (`{issue, item_id, wave?, phase?}`). A requested `phase` stamp when
+    `phase_cfg` is None (profile lacks `fields.phase`) is SKIPPED and counted —
+    never silently dropped without a trace (AC2)."""
+    phase_field_id = (phase_cfg or {}).get("id")
+    phase_options = (phase_cfg or {}).get("options", {})
+    stamps: list[FieldStamp] = []
+    skipped_phase = 0
+    for it in items:
+        issue = it["issue"]
+        item_id = it["item_id"]
+        wave = it.get("wave")
+        phase = it.get("phase")
+        if wave is not None:
+            stamps.append(FieldStamp(item_id, wave_field_id, "number", wave,
+                                      issue, "wave", wave))
+        if phase is not None:
+            if phase_field_id is None:
+                skipped_phase += 1
+                continue
+            if phase not in phase_options:
+                raise ValueError(
+                    f"unknown phase {phase!r}; valid: {', '.join(phase_options) or '(none configured)'}")
+            stamps.append(FieldStamp(item_id, phase_field_id, "single_select",
+                                      phase_options[phase], issue, "phase", phase))
+    return stamps, skipped_phase
+
+
+def chunk_stamps(stamps: list[FieldStamp], size: int = CHUNK_SIZE) -> list[list[FieldStamp]]:
+    """`stamps` split into ≤`size`-alias chunks, in order — one `gh api graphql`
+    request per chunk."""
+    return [stamps[i:i + size] for i in range(0, len(stamps), size)]
+
+
+def _value_fragment(kind: str, value) -> str:
+    if kind == "number":
+        return f"number:{int(value)}"
+    if kind == "single_select":
+        return f"singleSelectOptionId:{json.dumps(str(value))}"
+    raise ValueError(f"unsupported field kind {kind!r}")
+
+
+def build_stamp_mutation(stamps: list[FieldStamp], project_id: str) -> tuple[str, dict[str, FieldStamp]]:
+    """One aliased `updateProjectV2ItemFieldValue` mutation body for ≤CHUNK_SIZE
+    stamps (GraphQL alias-batching — one `gh api graphql` request instead of N).
+    Returns (mutation string, {alias: FieldStamp}) so a caller can map a
+    GraphQL error's `path` back to the failing (issue, field)."""
+    pid = json.dumps(project_id)
+    parts = []
+    alias_map: dict[str, FieldStamp] = {}
+    for i, s in enumerate(stamps):
+        alias = f"s{i}"
+        alias_map[alias] = s
+        parts.append(
+            f"{alias}: updateProjectV2ItemFieldValue(input:{{"
+            f"projectId:{pid}, itemId:{json.dumps(s.item_id)}, "
+            f"fieldId:{json.dumps(s.field_id)}, "
+            f"value:{{{_value_fragment(s.kind, s.value)}}}}}) "
+            f"{{ projectV2Item {{ id }} }}"
+        )
+    return "mutation{" + " ".join(parts) + "}", alias_map
+
+
+def parse_batch_response(response: dict, alias_map: dict[str, FieldStamp]
+                          ) -> tuple[list[FieldStamp], list[tuple[FieldStamp, str]]]:
+    """(succeeded, failed) for one chunk, read off the GraphQL response's
+    `data`/`errors` — the counted report's ONLY source (deliberately no extra
+    post-write read-back pass AC). A GraphQL partial-failure response
+    carries BOTH `data` (for the aliases that succeeded) and `errors[].path`
+    (the alias of each one that didn't); an alias with neither an error nor
+    data is counted as failed defensively, never silently dropped."""
+    errors_by_alias: dict[str, str] = {}
+    for err in (response.get("errors") or []):
+        path = err.get("path") or []
+        if path and path[0] in alias_map:
+            errors_by_alias[path[0]] = err.get("message", "unknown error")
+    data = response.get("data") or {}
+    succeeded: list[FieldStamp] = []
+    failed: list[tuple[FieldStamp, str]] = []
+    for alias, stamp in alias_map.items():
+        if alias in errors_by_alias:
+            failed.append((stamp, errors_by_alias[alias]))
+        elif data.get(alias):
+            succeeded.append(stamp)
+        else:
+            failed.append((stamp, "no data returned for this alias"))
+    return succeeded, failed
+
+
+def repair_command(stamp: FieldStamp) -> str:
+    """Idempotent single-item retry for one failed alias — a GraphQL field-set
+    is idempotent, so re-running just this stamp is always safe, no matter how
+    many times."""
+    return (f"python3 scripts/board-sync.py stamp-batch --issue {stamp.issue} "
+            f"--item-id {stamp.item_id} --{stamp.field_name} {stamp.display_value}")
+
+
+# --- field-value: read a project item's current field value ------------------
+def extract_field_value(data: dict, project_id: str, field_id: str) -> Optional[dict]:
+    """The current value of `field_id` on the issue's item in `project_id`
+    (`{"number": n}` / `{"name": ..., "optionId": ...}` / `{"text": ...}`), or
+    None if the issue isn't on that project / the field was never set. Matches
+    by field id (not name) — the profile only carries opaque field ids, never
+    the human-facing field NAME, so a name-keyed GraphQL lookup would need a
+    new required key; this stays ID-driven like the rest of the profile."""
+    issue = (data.get("data") or {}).get("repository", {}).get("issue")
+    items = ((issue or {}).get("projectItems") or {}).get("nodes") or []
+    for item in items:
+        if (item.get("project") or {}).get("id") != project_id:
+            continue
+        for fv in ((item.get("fieldValues") or {}).get("nodes") or []):
+            if (fv.get("field") or {}).get("id") != field_id:
+                continue
+            if "number" in fv:
+                return {"number": fv["number"]}
+            if "optionId" in fv:
+                return {"name": fv.get("name"), "optionId": fv["optionId"]}
+            if "text" in fv:
+                return {"text": fv["text"]}
+    return None
+
+
+# --- promote guards (pure decisions; board-sync.py wires the reads) ----------
+def wave_mismatch_guard(current_wave: Optional[int], target_wave: int) -> Optional[str]:
+    """None when `promote` may proceed (Wave field empty, or already == target —
+    an idempotent re-promote); an abort message otherwise (the field carries a
+    DIFFERENT wave — never silently overwritten AC3)."""
+    if current_wave is None or current_wave == target_wave:
+        return None
+    return (f"stub already carries Wave={current_wave} — refusing to overwrite with "
+            f"--wave {target_wave} (mismatch; re-check which wave this stub belongs "
+            "to, or pass the already-stamped wave to proceed idempotently)")
+
+
+def program_prd_refusal(is_program: bool, issue: int) -> Optional[str]:
+    """None when `promote` may proceed; a refusal message when the target is a
+    Program-PRD (never a promote target — it is the native anchor OVER Wellen,
+    not itself a Welle AC3)."""
+    if not is_program:
+        return None
+    return (f"#{issue} is a Program-PRD (`<!-- prd: program -->` marker or the "
+            "programType label) — refusing to promote it; a Program-PRD is a "
+            "native anchor over Wellen, never itself a promote target.")

package/scripts/build-kit.mjs

@@ -0,0 +1,116 @@
+/** Build the distributable kit from this public repository's current SSOT. */
+import { chmod, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectBundle } from '../src/lib/bundle.mjs';
+import { sha256 } from '../src/lib/hash.mjs';
+import { scrub } from './lib/scrub.mjs';
+import { auditExecRefs, auditModuleImports, auditSkillNameRefs } from './lib/audit-refs.mjs';
+
+const ROOT_FILES = ['LICENSE', 'README.md', 'PROVENANCE.md'];
+const DOC_ASSETS = ['index.html', 'methodology.html', 'methodology.svg', 'workflow.png'];
+
+const isBinary = (buf) => buf.includes(0);
+
+async function walk(dir) {
+  const files = [];
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); }
+  catch (error) { if (error.code === 'ENOENT') return files; throw error; }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...await walk(path));
+    else if (entry.isFile()) files.push(path);
+  }
+  return files.sort();
+}
+
+async function writeOut(path, content, mode = 0o644) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
+  await chmod(path, mode);
+}
+
+async function copySource(repoRoot, distDir, source, destination, mode = 0o644, shouldScrub = true) {
+  const raw = await readFile(join(repoRoot, source));
+  const content = shouldScrub && !isBinary(raw)
+    ? Buffer.from(scrub(raw.toString('utf8')), 'utf8') : raw;
+  await writeOut(join(distDir, destination), content, mode);
+  return content;
+}
+
+async function shipBundle(repoRoot, distDir, bundleFiles) {
+  const entries = [];
+  for (const file of bundleFiles) {
+    const content = await copySource(repoRoot, distDir, file.src, file.dest, file.mode);
+    entries.push({
+      path: file.dest, kind: file.kind, ownerSkill: file.ownerSkill,
+      surface: file.surface, sha256: sha256(content), mode: file.mode, origin: 'kit',
+    });
+  }
+  return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+async function shipRepositoryFiles(repoRoot, distDir, packageJson) {
+  for (const file of ROOT_FILES) await copySource(repoRoot, distDir, file, file, 0o644, false);
+  for (const file of DOC_ASSETS) {
+    await copySource(repoRoot, distDir, `docs/${file}`, `docs/${file}`);
+  }
+  for (const absolute of await walk(join(repoRoot, 'src'))) {
+    const path = `src/${relative(join(repoRoot, 'src'), absolute)}`;
+    await copySource(repoRoot, distDir, path, path);
+  }
+  const distributable = {
+    ...packageJson,
+    repository: {
+      type: 'git', url: 'git+https://github.com/iKon85/agent-workflow-kit.git',
+    },
+  };
+  await writeOut(join(distDir, 'package.json'), Buffer.from(`${JSON.stringify(distributable, null, 2)}\n`));
+}
+
+async function auditBuild(repoRoot, distDir, manifest, entries) {
+  const bodies = new Map();
+  for (const entry of entries) {
+    if (entry.path.endsWith('.md') || entry.path.endsWith('.py')) {
+      bodies.set(entry.path, await readFile(join(distDir, entry.path), 'utf8'));
+    }
+  }
+  const localModules = (await Promise.all(
+    ['scripts', '.claude/hooks'].map(async (dir) => {
+      try { return await readdir(join(repoRoot, dir)); } catch { return []; }
+    }),
+  )).flat().filter((name) => name.endsWith('.py')).map((name) => name.slice(0, -3));
+  const known = Object.keys(manifest.skills);
+  const published = known.filter((name) => manifest.skills[name].publish);
+  const read = (path) => bodies.get(path) ?? null;
+  const failures = [
+    ...auditExecRefs(entries, read).map((v) => `${v.file} -> ${v.ref}`),
+    ...auditModuleImports(entries, read, localModules).map((v) => `${v.file} -> ${v.module}`),
+    ...auditSkillNameRefs(entries, read, { known, published }).map((v) => `${v.file} -> ${v.skill}`),
+  ];
+  if (failures.length) throw new Error(`build-kit: dangling dependencies:\n${failures.join('\n')}`);
+}
+
+export async function buildKit({ repoRoot, distDir } = {}) {
+  repoRoot ??= join(dirname(fileURLToPath(import.meta.url)), '..');
+  distDir ??= join(repoRoot, 'dist-kit');
+  const manifest = JSON.parse(await readFile(join(repoRoot, '.claude/skills/skill-manifest.json'), 'utf8'));
+  const packageJson = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+  await rm(distDir, { recursive: true, force: true });
+  await mkdir(distDir, { recursive: true });
+  const { files } = await collectBundle(repoRoot, manifest);
+  const entries = await shipBundle(repoRoot, distDir, files);
+  await shipRepositoryFiles(repoRoot, distDir, packageJson);
+  await writeOut(join(distDir, 'agent-workflow-kit.package.json'), Buffer.from(
+    `${JSON.stringify({ kitVersion: packageJson.version, files: entries }, null, 2)}\n`,
+  ));
+  await auditBuild(repoRoot, distDir, manifest, entries);
+  return { distDir, kitVersion: packageJson.version, fileCount: entries.length };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  buildKit().then(({ distDir, kitVersion, fileCount }) => {
+    console.log(`built ${distDir} · kitVersion ${kitVersion} · ${fileCount} files`);
+  }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/scripts/build-kit.test.mjs

@@ -0,0 +1,59 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { buildKit } from './build-kit.mjs';
+
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+async function withBuild(fn) {
+  const dist = await mkdtemp(join(tmpdir(), 'awkit-build-'));
+  try { return await fn(dist, await buildKit({ repoRoot: REPO, distDir: dist })); }
+  finally { await rm(dist, { recursive: true, force: true }); }
+}
+
+test('historical v0.9.0 manifest remains an immutable golden fixture', async () => {
+  const fixture = await readFile(join(REPO, 'test/fixtures/v0.9.0-agent-workflow-kit.package.json'));
+  assert.equal(createHash('sha256').update(fixture).digest('hex'),
+    'a209e14b1a2e5b3bba63c16ee6a7d713b6acd9a1d11379bb07fdd1e3e4ca8b6c');
+  const manifest = JSON.parse(fixture);
+  assert.equal(manifest.kitVersion, '0.9.0');
+  assert.equal(manifest.files.length, 215);
+});
+
+test('current public SSOT builds deterministically', async () => {
+  const first = await withBuild(async (dist) => readFile(join(dist, 'agent-workflow-kit.package.json'), 'utf8'));
+  const second = await withBuild(async (dist) => readFile(join(dist, 'agent-workflow-kit.package.json'), 'utf8'));
+  assert.equal(first, second);
+});
+
+test('current build contains post-tag public files and repository metadata', async () => {
+  await withBuild(async (dist) => {
+    await readFile(join(dist, '.agents/skills/codex-adapter-sync/SKILL.md'));
+    await readFile(join(dist, 'scripts/program_graph.py'));
+    const pkg = JSON.parse(await readFile(join(dist, 'package.json'), 'utf8'));
+    assert.equal(pkg.repository.url, 'git+https://github.com/iKon85/agent-workflow-kit.git');
+  });
+});
+
+test('current build is self-contained and never reaches into a consumer checkout', async () => {
+  const source = await readFile(join(REPO, 'scripts/build-kit.mjs'), 'utf8');
+  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.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');
+});

package/scripts/check-kit-staleness.mjs

@@ -0,0 +1,45 @@
+/** Verify that the checked-in install manifest matches a fresh public-SSOT build. */
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildKit } from './build-kit.mjs';
+
+const index = (manifest) => new Map(manifest.files.map((file) => [file.path, file.sha256]));
+
+export function diffManifests(checked, built) {
+  const before = index(checked);
+  const after = index(built);
+  const added = [...after.keys()].filter((path) => !before.has(path)).sort();
+  const removed = [...before.keys()].filter((path) => !after.has(path)).sort();
+  const changed = [...after.keys()].filter(
+    (path) => before.has(path) && before.get(path) !== after.get(path),
+  ).sort();
+  return { added, removed, changed };
+}
+
+export async function checkKitStaleness({ repoRoot } = {}) {
+  repoRoot ??= join(dirname(fileURLToPath(import.meta.url)), '..');
+  const distDir = await mkdtemp(join(tmpdir(), 'awkit-staleness-'));
+  try {
+    await buildKit({ repoRoot, distDir });
+    const checked = JSON.parse(await readFile(join(repoRoot, 'agent-workflow-kit.package.json'), 'utf8'));
+    const built = JSON.parse(await readFile(join(distDir, 'agent-workflow-kit.package.json'), 'utf8'));
+    const diff = diffManifests(checked, built);
+    const drift = Object.values(diff).some((paths) => paths.length);
+    return { status: drift ? 'drift' : 'ok', ...diff };
+  } finally {
+    await rm(distDir, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  checkKitStaleness().then((result) => {
+    if (result.status === 'ok') return console.log('kit:staleness — OK');
+    console.error('kit:staleness — DRIFT');
+    for (const key of ['added', 'removed', 'changed']) {
+      if (result[key].length) console.error(`  ${key}: ${result[key].join(', ')}`);
+    }
+    process.exitCode = 1;
+  }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/scripts/check-kit-staleness.test.mjs

@@ -0,0 +1,19 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { diffManifests } from './check-kit-staleness.mjs';
+
+test('manifest parity reports no drift for identical path hashes', () => {
+  const manifest = { files: [{ path: 'a', sha256: 'one' }] };
+  assert.deepEqual(diffManifests(manifest, manifest), { added: [], removed: [], changed: [] });
+});
+
+test('manifest parity counts added, removed, and changed files', () => {
+  const checked = { files: [{ path: 'gone', sha256: '1' }, { path: 'same', sha256: '1' }, { path: 'changed', sha256: '1' }] };
+  const built = { files: [{ path: 'new', sha256: '1' }, { path: 'same', sha256: '1' }, { path: 'changed', sha256: '2' }] };
+  assert.deepEqual(diffManifests(checked, built), {
+    added: ['new'], removed: ['gone'], changed: ['changed'],
+  });
+});