@ikon85/agent-workflow-kit 0.10.0

package/scripts/program_graph_validate.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""program_graph_validate.py — the 8 Programm-Graph validation axes.
+
+Structural (blocking): Zyklen, Rückwärts-Refs über Wellengrenzen, Kapazität,
+Phasen-Optionen, Revisions-Kohärenz. Advisory (counted, shown, non-blocking):
+Gate-Slice-Struktur-Verdacht, Rollup-Kette-Lücken, Scope-Abdeckung-Lücken — these
+feed the counted Vorschau-Gate report, but a human decides whether an incomplete
+draft proceeds; only structural errors are hard.
+
+PURE — no gh / no I/O / no board_config. `phase_options` is injected as a plain
+parameter (caller reads it defensively from the board profile CR#1).
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from program_graph_parse import ProgramGraph, SliceBlock, WaveRow
+
+# Gate-Legende (docs/agents/wave-anchor-template.md): "—" = AFK/no gate; the four
+# non-AFK tags mark a Gate-Slice (Struktur-Verdacht check).
+GATE_TYPES = {"🧭", "🔬", "📐", "📝"}
+
+
+def find_cycles(slices: list[SliceBlock]) -> list[list[str]]:
+    """Cycles in the blocked_by graph, each as the ordered path incl. the repeated
+    closing id. Unknown targets are ignored here (see `find_unknown_refs`)."""
+    ids = {s.local_id for s in slices}
+    graph = {s.local_id: [b for b in s.blocked_by if b in ids] for s in slices}
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color = {k: WHITE for k in graph}
+    cycles: list[list[str]] = []
+    path: list[str] = []
+
+    def dfs(node: str) -> None:
+        color[node] = GRAY
+        path.append(node)
+        for nxt in graph.get(node, []):
+            if color[nxt] == GRAY:
+                idx = path.index(nxt)
+                cycles.append(path[idx:] + [nxt])
+            elif color[nxt] == WHITE:
+                dfs(nxt)
+        path.pop()
+        color[node] = BLACK
+
+    for node in graph:
+        if color[node] == WHITE:
+            dfs(node)
+    return cycles
+
+
+def find_duplicate_slice_ids(slices: list[SliceBlock]) -> list[str]:
+    """Duplicate `local_id`s make the slice graph ambiguous: find_cycles,
+    find_backward_refs and the rollup membership dict all key slices by
+    local_id (last-wins dict lookups), so a second `#### 1a` block silently
+    shadows the first block's blocked_by edges — a blocking cycle living in the
+    shadowed block would otherwise go undetected. Same structural error class
+    as a cycle (Bug 3)."""
+    seen: set[str] = set()
+    dupes: list[str] = []
+    for s in slices:
+        if s.local_id in seen and s.local_id not in dupes:
+            dupes.append(s.local_id)
+        seen.add(s.local_id)
+    return [f"doppelte Slice-ID '{lid}' im Wellenplan — IDs müssen eindeutig sein"
+            for lid in dupes]
+
+
+def find_unknown_refs(slices: list[SliceBlock]) -> list[str]:
+    """blocked_by targets that name no existing slice local-id."""
+    ids = {s.local_id for s in slices}
+    return [f"Slice {s.local_id}: blocked_by unbekannte Referenz '{b}'"
+            for s in slices for b in s.blocked_by if b not in ids]
+
+
+def find_backward_refs(slices: list[SliceBlock]) -> list[str]:
+    """blocked_by a LATER wave's slice = a backward ref across the wave boundary
+    (a slice may only depend on its own or an earlier wave). Blocking."""
+    by_id = {s.local_id: s for s in slices}
+    out = []
+    for s in slices:
+        if s.wave is None:
+            continue
+        for b in s.blocked_by:
+            target = by_id.get(b)
+            if target is None or target.wave is None:
+                continue
+            if target.wave > s.wave:
+                out.append(
+                    f"Slice {s.local_id} (Welle {s.wave}) blockiert durch {b} "
+                    f"(Welle {target.wave}) — Rückwärts-Ref über Wellengrenze")
+    return out
+
+
+def find_gate_dependents_outside_wave(slices: list[SliceBlock]) -> list[str]:
+    """A Gate-Slice (🧭/🔬/📐/📝) with dependents in a DIFFERENT wave is a
+    structural suspicion — gate-slices are meant to be wave-local (AFK-safe)."""
+    warnings = []
+    for s in slices:
+        if s.gate not in GATE_TYPES:
+            continue
+        outside = [o for o in slices if s.local_id in o.blocked_by and o.wave != s.wave]
+        if outside:
+            names = ", ".join(f"{o.local_id} (Welle {o.wave})" for o in outside)
+            warnings.append(
+                f"Gate-Slice {s.local_id} (Welle {s.wave}) hat wellen-fremde "
+                f"Abhängige: {names} — Struktur-Verdacht")
+    return warnings
+
+
+def check_capacity(waves: list[WaveRow], max_children: int = 100) -> list[str]:
+    """GitHub's 100-children-per-parent limit, for the PRD→Welle + Welle→Slice fan-outs."""
+    errors = []
+    if len(waves) > max_children:
+        errors.append(f"{len(waves)} Wellen im PRD > {max_children} "
+                      f"(GitHub Sub-Issue-Limit je Parent)")
+    for w in waves:
+        if len(w.slice_ids) > max_children:
+            errors.append(f"Welle {w.number}: {len(w.slice_ids)} Slices > "
+                          f"{max_children} (GitHub Sub-Issue-Limit je Parent)")
+    return errors
+
+
+def check_phase_options(graph: ProgramGraph, phase_options: Optional[list[str]]) -> list[str]:
+    """Every Phase value used (Wellenplan rows or Slice metadata) must be a
+    configured option of the board's Phase field. `phase_options=None` means the
+    profile has no `fields.phase` at all — a visible setup hint, never a crash
+    (CRITICAL RECONCILIATION #2), and only if the PRD uses phases at all
+    (a phase-less PRD is unaffected — Phasen sind optional)."""
+    used = {w.phase for w in graph.waves if w.phase}
+    used |= {s.phase for s in graph.slices if s.phase}
+    if not used:
+        return []
+    if phase_options is None:
+        return ["keine Phase-Feld-Konfiguration im Board-Profil gefunden — "
+                "Setup-Hinweis: `fields.phase` ergänzen (/setup-workflow)"]
+    unknown = sorted(p for p in used if p not in phase_options)
+    return [f"Phase '{p}' ist keine Option des Phase-Felds im Board-Profil "
+            f"— Setup-Hinweis: Option in /setup-workflow ergänzen" for p in unknown]
+
+
+def _check_slice_membership(graph: ProgramGraph) -> list[str]:
+    """Each Slices-column id must have a Slice-block; each Slice-block must be
+    referenced by exactly one wave and belong to a wave that exists."""
+    gaps: list[str] = []
+    wave_by_number = {w.number: w for w in graph.waves}
+    membership: dict[str, int] = {s.local_id: 0 for s in graph.slices}
+    for w in graph.waves:
+        for sid in w.slice_ids:
+            if sid in membership:
+                membership[sid] += 1
+            else:
+                gaps.append(f"Welle {w.number}: Slice '{sid}' in der Slices-Spalte "
+                           f"hat keinen Slice-Block")
+    for sid, count in membership.items():
+        if count == 0:
+            gaps.append(f"Slice {sid}: in keiner Wellenplan-Zeile referenziert")
+        elif count > 1:
+            gaps.append(f"Slice {sid}: in {count} Wellenplan-Zeilen referenziert "
+                       f"(erwartet genau 1)")
+    for s in graph.slices:
+        if s.wave is None:
+            gaps.append(f"Slice {s.local_id}: kein wave-Feld gesetzt")
+        elif s.wave not in wave_by_number:
+            gaps.append(f"Slice {s.local_id}: Welle {s.wave} existiert nicht im Wellenplan")
+    return gaps
+
+
+def _check_wave_completeness(graph: ProgramGraph) -> list[str]:
+    """Every wave carries ≥1 slice + a Gate (+ a Phase if the PRD uses phases)."""
+    gaps: list[str] = []
+    phases_used = any(w.phase for w in graph.waves)
+    for w in graph.waves:
+        if not w.slice_ids:
+            gaps.append(f"Welle {w.number}: keine Slices")
+        if not w.gate.strip():
+            gaps.append(f"Welle {w.number}: kein Gate-Wert gesetzt")
+        if phases_used and not w.phase:
+            gaps.append(f"Welle {w.number}: keine Phase gesetzt, obwohl das "
+                       f"Programm Phasen nutzt")
+    return gaps
+
+
+def _check_phase_gate_pairing(graph: ProgramGraph) -> list[str]:
+    """Every used Phase has a checklist Gate-Kriterium, and every checklist entry
+    names a Phase some wave uses."""
+    gaps: list[str] = []
+    phases_used = {w.phase for w in graph.waves if w.phase}
+    for phase in phases_used:
+        if phase not in graph.phase_gates:
+            gaps.append(f"Phase {phase}: kein Gate-Kriterium in der "
+                       f"Phasen-Gates-Checkliste")
+    for phase in graph.phase_gates:
+        if phase not in phases_used:
+            gaps.append(f"Phase {phase}: keine Welle referenziert diese Phase "
+                       f"(Checklisten-Waise)")
+    return gaps
+
+
+def check_rollup(graph: ProgramGraph) -> list[str]:
+    """Vertical completeness: the Programm→Welle→Slice rollup chain is closed
+    (slice↔wave membership + per-wave completeness + phase↔gate pairing)."""
+    return [*_check_slice_membership(graph), *_check_wave_completeness(graph),
+            *_check_phase_gate_pairing(graph)]
+
+
+def check_scope_coverage(graph: ProgramGraph) -> tuple[int, int, list[str]]:
+    """Horizontal completeness: every Scope-Item is covered by ≥1 wave, every wave
+    covers ≥1 Scope-Item or is explicitly marked `enabler`, and every covers token
+    names a declared Scope-Item (an `S99` typo is a non-blocking gap of its own —
+    advisory, and doesn't affect the covered/total count below). Returns
+    (covered_count, total_count, gap_messages)."""
+    gaps: list[str] = []
+    covered_ids: set = set()
+    for w in graph.waves:
+        if not w.covers and not w.is_enabler:
+            gaps.append(f"Welle {w.number}: keine Scope-Abdeckung und nicht als "
+                       f"Enabler markiert")
+        for token in w.covers:
+            if token not in graph.scope_items:
+                gaps.append(f"Welle {w.number}: covers unbekanntes Scope-Item "
+                           f"'{token}'")
+        covered_ids.update(w.covers)
+    covered = 0
+    for sid in graph.scope_items:
+        if sid in covered_ids:
+            covered += 1
+        else:
+            gaps.append(f"Scope-Item {sid}: von keiner Welle abgedeckt")
+    return covered, len(graph.scope_items), gaps
+
+
+def check_revision_coherence(plan_revision: Optional[int],
+                             stub_revisions: Optional[list[dict]]) -> list[str]:
+    """A published Welle-Stub whose `<!-- program-revision: rN -->` marker (stamped
+    by `to-waves`) no longer matches the PRD's plan_revision is stale — it blocks
+    loudly instead of silently building from an outdated plan.
+
+    `stub_revisions` (`[{"label": str, "revision": int | None}, …]`) is pre-fetched
+    by the caller (this module stays I/O-free); the CLI passes `[]` when no stubs
+    are fetched pre-publish, and callers wire in the real fetch via the same
+    signature."""
+    if not stub_revisions:
+        return []
+    if plan_revision is None:
+        return ["PRD hat kein plan_revision — Revisions-Kohärenz nicht prüfbar"]
+    out = []
+    for stub in stub_revisions:
+        label = stub.get("label", "?")
+        rev = stub.get("revision")
+        if rev is None:
+            out.append(f"{label}: kein program-revision-Marker gefunden")
+        elif rev != plan_revision:
+            out.append(f"{label}: program-revision r{rev} != PRD plan_revision "
+                       f"r{plan_revision} — stale")
+    return out

package/scripts/program_sync.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""program_sync.py — Wellenplan Status-resync for `board-sync.py program-sync`
+(plan step 9b(d); Status column amendment).
+
+A Program-PRD's `## Wellenplan` table is its OWN grammar (Welle/Status/Name/
+Slices/Gate/covers — parsed by `program_graph_parse.py`), one level above a
+Welle-Anchor's own Slices-table. `anchor-sync` (`anchor_table.py`) already
+regenerates an Anchor's Slice-row Status/Branch from its native sub-issues;
+`program-sync` does the SAME KIND of thing one graph level up — a PRD's native
+sub-issues are its promoted Wave-Anchor stubs — but deliberately as a SEPARATE
+command over a SEPARATE grammar (plan 9b(d): "program-sync statt
+anchor-sync-Überladung"), not a second table format bolted onto either module.
+
+`WaveRow` carries a dedicated `status` field (docs/adr/0054 §Folge-Arbeit forbids
+only a SECOND Wellenplan table format, not a Status COLUMN within the one
+grammar). The volatile Status therefore lives in its own cell, refreshed
+MONOTONICALLY (never ✅→🔄→⬜, mirroring `anchor_table.refresh_status_cell`'s
+never-regress rule) — the `Name` cell is left entirely untouched by this sync:
+hand annotations there always survive verbatim, and Status is the only column
+`program-sync` ever rewrites.
+
+PURE — no gh / no I/O / no board_config. Only imports `WaveRow` from
+`program_graph`'s public facade (never re-implementing the Wellenplan
+parser/renderer — `program_graph_parse.py` owns that grammar).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from typing import Optional
+
+from program_graph import WaveRow
+
+_WAVE_NUMBER_RE = re.compile(r"^\s*Welle\s+(\d+)\s*[—–-]", re.IGNORECASE)
+_STATUS_RANK = {"⬜": 0, "🔄": 1, "✅": 2}
+
+_WELLENPLAN_BLOCK_RE = re.compile(
+    r"<!--\s*wellenplan:start\s*-->.*?<!--\s*wellenplan:end\s*-->", re.DOTALL)
+
+
+def extract_wave_number_from_title(title: str) -> Optional[int]:
+    """The wave number out of a promoted Wave-Anchor's `Welle <N> — <Thema>`
+    title (the same convention `board-sync.py`'s `wave_title()` writes), or
+    None for a title that isn't wave-prefixed (not yet promoted / foreign)."""
+    m = _WAVE_NUMBER_RE.match(title or "")
+    return int(m.group(1)) if m else None
+
+
+def wave_status_token(entry: Optional[dict], roles: dict) -> str:
+    """⬜ (no matching native child yet — not promoted) · 🔄 (an in-flight
+    board status) · ✅ (the done-role status). Deliberately NOT
+    `anchor_table.status_token_from_board` — a Wave-Anchor issue is never
+    `closes`-referenced by a PR (board-sync.md convention: `closes` never
+    targets an Anker), so a Wave's completion is read off its OWN board Status
+    field, not a merged-PR check.
+
+    Status NAMES come from the profile's role map (`roles["done"]`,
+    `roles["inProgress"]`/`roles["review"]`), passed as a plain dict so
+    this module stays pure. Empty roles → every status reads as ⬜ (the
+    monotone refresh never regresses a hand-set cell)."""
+    if entry is None:
+        return "⬜"
+    status = entry.get("status")
+    if status and status == roles.get("done"):
+        return "✅"
+    if status and status in ({roles.get("inProgress"), roles.get("review")} - {None}):
+        return "🔄"
+    return "⬜"
+
+
+def refresh_wave_status(existing_status: str, token: str) -> str:
+    """Refresh a Wellenplan row's Status cell from the board, MONOTONICALLY
+    (never regress ✅→🔄→⬜ — mirrors `anchor_table.refresh_status_cell`'s
+    never-regress rule). An existing cell that isn't a known token (unset,
+    blank, or hand-typed garbage) ranks below ⬜ (rank -1), so the first sync
+    always sets it."""
+    existing_rank = _STATUS_RANK.get(existing_status, -1)
+    token_rank = _STATUS_RANK.get(token, -1)
+    if token_rank < existing_rank:
+        return existing_status
+    return existing_status if existing_status == token else token
+
+
+def sync_wellenplan_status(waves: list[WaveRow], board: dict, roles: dict) -> list[WaveRow]:
+    """A fresh `WaveRow` list with each row's `status` field refreshed from
+    `board` — the SAME `{issue: {title, status, prs}}` shape
+    `anchor_table.extract_anchor_board_data` already produces (no second query,
+    no second parse: the PRD's native sub-issues — its promoted Wave-Anchor
+    stubs — are fetched exactly like an Anchor fetches its Slice sub-issues).
+    The `issue` field (the navigation link to the wave's own issue) is
+    FILLED from the matching board child but never overwritten — once stamped
+    it is identity, a later title rename must not re-point it. Every other
+    WaveRow field (Name/Phase/Slices/Gate/covers/is_enabler) round-trips
+    untouched — those are stable Plan columns (or, for Name, hand-owned prose),
+    never board-derived."""
+    by_wave_number: dict[int, tuple[int, dict]] = {}
+    for issue_no, entry in board.items():
+        n = extract_wave_number_from_title(entry.get("title", ""))
+        if n is not None:
+            by_wave_number[n] = (issue_no, entry)
+    out: list[WaveRow] = []
+    for w in waves:
+        hit = by_wave_number.get(w.number)
+        entry = hit[1] if hit else None
+        issue = w.issue if w.issue is not None else (hit[0] if hit else None)
+        out.append(replace(w, issue=issue,
+                           status=refresh_wave_status(w.status, wave_status_token(entry, roles))))
+    return out
+
+
+_PHASE_GATES_HEADING_RE = re.compile(r"^##\s+Phasen-Gates\s*$")
+_H2_LINE_RE = re.compile(r"^##\s+")
+_UNCHECKED_GATE_RE = re.compile(r"^(\s*-\s+\[) (\]\s*(P\d+):.*)$")
+
+
+def checkoff_phase_gates(body: str, waves: list[WaveRow], today: str) -> tuple[str, list[str]]:
+    """Check off `## Phasen-Gates` entries whose phase is mechanically complete —
+    every Wellenplan wave carrying that phase has status ✅ (upward
+    propagation). Monotone + idempotent: only an UNCHECKED box whose phase just
+    completed is flipped (`[ ]` → `[x]`, with an `— alle Wellen ✅ (<today>)`
+    suffix stamped once); a checked box is never touched again, a phase no wave
+    uses is never checked (that is a Checklisten-Waise — validate-graph's
+    finding, not ours). Only lines inside the `## Phasen-Gates` section are
+    considered. Returns (new_body, newly_checked_phase_ids)."""
+    waves_by_phase: dict[str, list[WaveRow]] = {}
+    for w in waves:
+        if w.phase:
+            waves_by_phase.setdefault(w.phase, []).append(w)
+    done_phases = {p for p, ws in waves_by_phase.items()
+                   if all(w.status == "✅" for w in ws)}
+    lines = body.splitlines()
+    in_section = False
+    checked: list[str] = []
+    for i, ln in enumerate(lines):
+        if _PHASE_GATES_HEADING_RE.match(ln):
+            in_section = True
+            continue
+        if in_section and _H2_LINE_RE.match(ln):
+            in_section = False
+        if not in_section:
+            continue
+        m = _UNCHECKED_GATE_RE.match(ln)
+        if m and m.group(3) in done_phases:
+            lines[i] = f"{m.group(1)}x{m.group(2)} — alle Wellen ✅ ({today})"
+            checked.append(m.group(3))
+    new_body = "\n".join(lines) + ("\n" if body.endswith("\n") else "")
+    return new_body, checked
+
+
+def splice_wellenplan_table(body: str, rendered_block: str) -> str:
+    """Replace the `<!-- wellenplan:start/end -->` block with a freshly
+    rendered one (`program_graph.render_wellenplan_table`'s output already
+    carries its own markers). Mirrors `anchor_table.splice_slice_table`'s
+    marker-replace mechanic — kept HERE rather than shared with it, because
+    this is a different table grammar entirely (plan 9b(d))."""
+    if not _WELLENPLAN_BLOCK_RE.search(body):
+        raise ValueError(
+            "no Wellenplan table found in program body (needs "
+            "`<!-- wellenplan:start -->`/`<!-- wellenplan:end -->` markers)")
+    return _WELLENPLAN_BLOCK_RE.sub(lambda _m: rendered_block, body)

package/scripts/release-delta-guard.mjs

@@ -0,0 +1,96 @@
+/** Block shipped changes whose version or checked manifest does not match a fresh build. */
+import { execFileSync } from 'node:child_process';
+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 byPath = (manifest) => new Map(manifest.files.map((entry) => [entry.path, entry.sha256]));
+
+export function manifestDelta(before, after) {
+  const old = byPath(before);
+  const fresh = byPath(after);
+  return {
+    added: [...fresh.keys()].filter((path) => !old.has(path)).sort(),
+    removed: [...old.keys()].filter((path) => !fresh.has(path)).sort(),
+    changed: [...fresh.keys()].filter((path) => old.has(path) && old.get(path) !== fresh.get(path)).sort(),
+  };
+}
+
+const hasDelta = (delta) => Object.values(delta).some((paths) => paths.length);
+const describe = (delta) => ['added', 'removed', 'changed']
+  .filter((kind) => delta[kind].length)
+  .map((kind) => `${kind}: ${delta[kind].join(', ')}`).join('; ');
+
+export function recommendBump(delta) {
+  if (delta.removed.length) return 'major';
+  if (delta.added.length) return 'minor';
+  return delta.changed.length ? 'patch' : null;
+}
+
+function bumpKind(before, after) {
+  const a = before.split('.').map(Number);
+  const b = after.split('.').map(Number);
+  if (b[0] > a[0]) return 'major';
+  if (b[0] === a[0] && b[1] > a[1]) return 'minor';
+  if (b[0] === a[0] && b[1] === a[1] && b[2] > a[2]) return 'patch';
+  return null;
+}
+
+export function assessRelease(input) {
+  const delta = manifestDelta(input.baseManifest, input.builtManifest);
+  const checkedDrift = manifestDelta(input.checkedManifest, input.builtManifest);
+  const errors = [];
+  if (hasDelta(delta) && input.currentVersion === input.baseVersion) {
+    errors.push(`shipped delta has no version bump (${describe(delta)}); version remains ${input.currentVersion}`);
+  }
+  if (input.checkedManifest.kitVersion !== input.currentVersion) {
+    errors.push(`checked manifest version ${input.checkedManifest.kitVersion} != package ${input.currentVersion}`);
+  }
+  for (const path of checkedDrift.removed) errors.push(`checked manifest dead entry: ${path}`);
+  if (checkedDrift.added.length || checkedDrift.changed.length) {
+    errors.push(`checked manifest is stale (${describe(checkedDrift)})`);
+  }
+  const recommendedBump = recommendBump(delta);
+  const actual = bumpKind(input.baseVersion, input.currentVersion);
+  const rank = { patch: 1, minor: 2, major: 3 };
+  if (hasDelta(delta) && input.currentVersion !== input.baseVersion && !actual) {
+    errors.push(`invalid version transition: ${input.baseVersion} -> ${input.currentVersion}`);
+  }
+  if (recommendedBump && actual && rank[actual] < rank[recommendedBump]) {
+    errors.push(`${actual} bump is smaller than recommended ${recommendedBump} (${describe(delta)})`);
+  }
+  return { ok: errors.length === 0, errors, delta, recommendedBump };
+}
+
+function gitShowJson(repoRoot, ref, path) {
+  return JSON.parse(execFileSync('git', ['show', `${ref}:${path}`], { cwd: repoRoot, encoding: 'utf8' }));
+}
+
+export async function checkReleaseDelta({ repoRoot, baseRef = 'origin/main' } = {}) {
+  repoRoot ??= join(dirname(fileURLToPath(import.meta.url)), '..');
+  const distDir = await mkdtemp(join(tmpdir(), 'awkit-release-guard-'));
+  try {
+    await buildKit({ repoRoot, distDir });
+    const currentPackage = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+    return assessRelease({
+      baseVersion: gitShowJson(repoRoot, baseRef, 'package.json').version,
+      currentVersion: currentPackage.version,
+      baseManifest: gitShowJson(repoRoot, baseRef, 'agent-workflow-kit.package.json'),
+      checkedManifest: JSON.parse(await readFile(join(repoRoot, 'agent-workflow-kit.package.json'), 'utf8')),
+      builtManifest: JSON.parse(await readFile(join(distDir, 'agent-workflow-kit.package.json'), 'utf8')),
+    });
+  } finally { await rm(distDir, { recursive: true, force: true }); }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const baseIndex = process.argv.indexOf('--base');
+  checkReleaseDelta({ baseRef: baseIndex < 0 ? undefined : process.argv[baseIndex + 1] })
+    .then((result) => {
+      if (result.ok) return console.log(`release:guard — OK${result.recommendedBump ? ` (${result.recommendedBump})` : ''}`);
+      console.error('release:guard — BLOCKED');
+      for (const error of result.errors) console.error(`  ${error}`);
+      process.exitCode = 1;
+    }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/scripts/release-delta-guard.test.mjs

@@ -0,0 +1,53 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { assessRelease } from './release-delta-guard.mjs';
+
+const file = (path, sha256) => ({ path, sha256 });
+
+test('an unbumped shipped change is blocked with its concrete delta', () => {
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.2.3',
+    baseManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'old')] },
+    builtManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'new')] },
+    checkedManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'old')] },
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.delta.changed, ['skill.md']);
+  assert.match(result.errors.join('\n'), /skill\.md/);
+  assert.match(result.errors.join('\n'), /version remains 1\.2\.3/);
+});
+
+test('dead checked-manifest entries are rejected', () => {
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.3.0',
+    baseManifest: { kitVersion: '1.2.3', files: [] },
+    builtManifest: { kitVersion: '1.3.0', files: [] },
+    checkedManifest: { kitVersion: '1.3.0', files: [file('gone.md', 'old')] },
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.errors.join('\n'), /dead entry: gone\.md/);
+});
+
+test('a matching regenerated manifest and semantic bump pass', () => {
+  const current = { kitVersion: '1.3.0', files: [file('new.md', 'one')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.3.0',
+    baseManifest: { kitVersion: '1.2.3', files: [] }, builtManifest: current,
+    checkedManifest: current,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.recommendedBump, 'minor');
+});
+
+test('shipped content rejects downgrade and malformed version transitions', () => {
+  for (const currentVersion of ['1.1.0', 'banana']) {
+    const current = { kitVersion: currentVersion, files: [file('skill.md', 'new')] };
+    const result = assessRelease({
+      baseVersion: '1.2.3', currentVersion,
+      baseManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'old')] },
+      builtManifest: current, checkedManifest: current,
+    });
+    assert.equal(result.ok, false, currentVersion);
+    assert.match(result.errors.join('\n'), /invalid version transition: 1\.2\.3 ->/);
+  }
+});

package/scripts/test_board_sync_create_idempotency.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Regression test for marker-aware board issue creation."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+
+PROFILE = {
+    "repo": "example/kit",
+    "project": {"number": 1, "owner": "example", "nodeId": "PVT_test"},
+    "fields": {
+        "status": {"id": "STATUS", "options": {}},
+        "wave": "WAVE",
+        "cluster": "CLUSTER",
+        "specPath": "SPEC",
+        "planPath": "PLAN",
+    },
+    "labels": {
+        "readyForAgent": "ready-for-agent",
+        "typePrefix": "type:",
+        "clusterType": "type:cluster",
+        "waveStub": "wave-stub",
+    },
+    "branchPrefixes": ["feat", "fix"],
+    "prMarkers": {"partOf": "Part of", "retroMarker": "Retro", "retroValues": []},
+    "headings": {"vorBau": "Clarify Before Build"},
+}
+
+
+def load_board_sync():
+    with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False) as profile:
+        profile.write("<!-- board-sync:profile -->\n```json\n")
+        json.dump(PROFILE, profile)
+        profile.write("\n```\n")
+        profile_path = profile.name
+    os.environ["BOARD_SYNC_PROFILE"] = profile_path
+    spec = importlib.util.spec_from_file_location(
+        "board_sync_create_test", Path(__file__).with_name("board-sync.py")
+    )
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    Path(profile_path).unlink()
+    return module
+
+
+bs = load_board_sync()
+
+
+class FakeGh:
+    def __init__(self, marker: str):
+        self.marker = marker
+        self.created = False
+        self.calls: list[list[str]] = []
+
+    def __call__(self, args: list[str]) -> str:
+        self.calls.append(args)
+        joined = " ".join(args)
+        if "issue list" in joined:
+            if not self.created:
+                return "[]"
+            return json.dumps([
+                {
+                    "number": 101,
+                    "url": "https://github.com/example/kit/issues/101",
+                    "body": self.marker,
+                }
+            ])
+        if "issue create" in joined:
+            self.created = True
+            return "https://github.com/example/kit/issues/101\n"
+        if "project item-add" in joined:
+            return '{"id":"PVTI_test"}'
+        return ""
+
+
+class MarkerAwareCreateTest(unittest.TestCase):
+    def test_identical_program_leaf_retry_reuses_existing_issue(self):
+        marker = "<!-- program-leaf-source: program-x/1a -->"
+        fake = FakeGh(marker)
+        original = bs._gh
+        bs._gh = fake
+        try:
+            with tempfile.NamedTemporaryFile("w", suffix=".md") as body:
+                body.write(marker + "\nOutcome: test\n")
+                body.flush()
+                argv = ["create", "--title", "Slice 1a", "--body-file", body.name]
+                self.assertEqual(bs.main(argv), 0)
+                self.assertEqual(bs.main(argv), 0)
+        finally:
+            bs._gh = original
+
+        creates = [call for call in fake.calls if "issue create" in " ".join(call)]
+        self.assertEqual(len(creates), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()