@ikon85/agent-workflow-kit 0.39.0 → 0.41.0

package/docs/adr/0009-teardown-authority-is-stateless-repository-classification.md

@@ -0,0 +1,101 @@
+# Teardown authority is stateless repository classification
+
+Status: accepted (2026-07-27, #320) — supersedes
+[ADR-0007](./0007-session-teardown-requires-provenance-bound-ownership.md)
+
+ADR-0007 derived teardown authority from persisted lifecycle evidence:
+ownership-proof refs acquired in atomic git transactions, frozen
+landing-attempt journals, baseline digests, no-follow identity binding, and a
+post-merge reload of the canonical cleanup policy. Every piece was locally
+justified, and the aggregate failed in practice: fifteen teardown/cleanup
+issues in two weeks (#245–#319), ~5,600 lines of lifecycle code, two recovery
+flags for the machinery's own bookkeeping, a legacy receipt contract, and
+refusals that did not name their cause (#319: 68,856 paths, 7.4 MB, zero
+actionable lines). The protection was aimed at narrow races between assessment
+and deletion; the cost was that ordinary sessions could no longer finish.
+
+We decided that teardown authority comes from the repository's **current
+state**, read at the moment of action, and from nothing else:
+
+1. **Git's own classification is the file taxonomy.** A tracked modification
+   blocks teardown. An untracked, non-ignored file blocks with a bounded
+   report (count plus top directories — never an unbounded path dump). An
+   ignored file is Scratch: the repository declared it not-work, and it is
+   deletable. "Ignored" means git's standard exclude sources
+   (`--exclude-standard`: repository `.gitignore` files, `.git/info/exclude`,
+   the global excludes file) — whatever the repository's own tooling treats as
+   ignored is deletion authority here too.
+2. **One hardcoded exception: `.env*` (basename glob).** Ignored yet
+   potentially irreplaceable. Before removal each `.env*` regular file is
+   compared byte-wise with its counterpart at the same relative path in the
+   main checkout, both opened no-follow: identical → derived copy, deletable;
+   divergent, absent in the main checkout, or either side not a regular file →
+   block with the exact files named. The check is a present-state comparison,
+   not a receipt.
+3. **The platform PR record authorizes branch deletion.** Force-deletion
+   requires exactly one PR matching the full tuple — this repository as base
+   repo, head repository equal to the base repo (no fork heads), head ref
+   equal to the branch name, base ref equal to the configured protected
+   branch, state merged — whose head SHA equals the branch tip OID; the OID
+   is re-read immediately before deletion, and zero matches, multiple
+   matches, an open PR on the same head, or any drift retains the branch.
+   Ancestry-merged branches (against a freshly fetched configured protected
+   branch — stale ancestry stops rather than guesses) delete normally. A
+   branch with neither stays and is reported. Without platform access this
+   degrades to ancestry-only, reported honestly.
+4. **Idempotency by re-check, not journal.** An interrupted landing is resumed
+   by re-running it; every step verifies present state (PR exists? merged?
+   worktree present?) and skips or proceeds. There is no persisted attempt
+   state to validate, archive, or recover.
+5. **A direct `/wrapup` invocation is the teardown authorization.** It lands
+   and tears down the worktree it runs in — including worktrees created by
+   external tools under foreign names and paths. The kit never conditions
+   teardown on its own naming or location conventions; the four classification
+   rules above are the only protection.
+6. **Deletion policy has exactly one configuration surface: the ignore
+   mechanism.** The consumer profile keeps structural facts only (worktree
+   root, templates, protected branches, sweep opt-in). `scratchPatterns` and
+   `landingGeneratedArtifactPatterns` are removed without migration —
+   including the shipped consumer migration that seeded them; making a file
+   deletable means ignoring it (ADR-0008's offered seeding remains the
+   supported way; its consequence about deriving `scratchPatterns` from the
+   seeded rules is obsolete with this decision).
+
+## Considered options
+
+- **Keep ADR-0007's provenance machinery:** rejected on empirical grounds. The
+  races it closes (a foreign file occupying an assessed path between
+  assessment and deletion, a same-name branch created concurrently) are rare
+  and low-harm next to the observed failure mode: routine teardown becoming
+  impossible and each repair adding machinery. The branch race is additionally
+  closed cheaper by the tip-SHA/PR comparison.
+- **Shipping default scratch patterns:** rejected. A default allowlist of the
+  deletable restarts the pattern catalog and its seeding, sync, and dialect
+  problems; `.gitignore` already encodes the same fact with universal
+  tooling.
+- **Migrating existing profiles and receipts:** rejected. The green-slate cut
+  is deliberate (#320): old keys are ignored, journaled attempts are inert
+  files, and no code path reads either. Maintaining both models would preserve
+  the complexity this decision removes.
+- **Location heuristic for externally created worktrees (land, don't tear
+  down):** rejected by the user. `/wrapup` means tear down; splitting the
+  outcome by worktree origin reintroduces an ownership notion.
+
+## Consequences
+
+- A worktree whose only untracked content is ignored dependency or build
+  output is removable with zero configuration. #319's failure class cannot
+  occur.
+- Refusals are bounded and name their cause; the fix is always visible
+  (commit the tracked change, handle the named `.env*`, ignore or remove the
+  named untracked files).
+- The accepted residual risk is explicit: between assessment and deletion a
+  file could in principle be replaced; a valuable file a consumer keeps
+  gitignored outside `.env*` is deletable at teardown. We trade these narrow
+  windows for a lifecycle that ordinary sessions can actually complete.
+- Planning sessions stop being a special case: durable content lands through
+  wrapup's Content route as ordinary work, scratch dies with the worktree,
+  and worktree creation binds to implementation, not planning.
+- The lifecycle implementation shrinks from a transaction protocol to a
+  classification function plus plumbing; its tests shift from race
+  choreography to classification truth tables.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "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": {

package/scripts/pr-body-check.py

@@ -208,13 +208,26 @@ def fetch_pr_body(branch: str):
     return out if rc == 0 else None
 
 
+def _anchor_labels() -> set:
+    """Labels that mark an issue as a never-auto-close anchor: the wave
+    cluster label plus the board profile's Program-PRD label (a Program-PRD
+    is closed last, manually — `closes` must never target it)."""
+    labels = {"type:cluster"}
+    try:
+        import board_config
+        labels.add(board_config.program_type_label(board_config.load_board_config()))
+    except Exception:
+        labels.add("type:program")  # profile unavailable → literal default
+    return labels
+
+
 def fetch_is_anchor(number: int) -> bool:
-    """True wenn das Issue selbst ein Wellen-Anker ist (Label type:cluster)."""
+    """True wenn das Issue selbst ein Anker ist (type:cluster oder Program-PRD)."""
     rc, out = _run(["gh", "issue", "view", str(number),
                     "--json", "labels", "-q", ".labels[].name"])
     if rc != 0:
         return False  # fail-open in den Leaf-Pfad (bisheriges Verhalten)
-    return "type:cluster" in out.splitlines()
+    return bool(_anchor_labels() & set(out.splitlines()))
 
 
 def resolve_has_e2e_na(args, branch: str) -> bool:

package/scripts/test_pr_body_check.py

@@ -79,6 +79,16 @@ class ExistingBodyRules(unittest.TestCase):
     def test_retro_line_still_required(self):
         self.assertTrue(any("Retro" in item for item in pbc.check_pr_body("closes #149", 149, None)))
 
+    def test_program_prd_label_counts_as_anchor(self):
+        with mock.patch.object(pbc, "_run",
+                               return_value=(0, "type:program\npriority:medium")):
+            self.assertTrue(pbc.fetch_is_anchor(320))
+
+    def test_cluster_label_still_counts_as_anchor(self):
+        with mock.patch.object(pbc, "_run",
+                               return_value=(0, "type:cluster")):
+            self.assertTrue(pbc.fetch_is_anchor(41))
+
     def test_wave_pr_still_requires_part_of_without_closing_anchor(self):
         body = f"Part of #130\ncloses #149\n{RETRO}"
         self.assertEqual(pbc.check_pr_body(body, 130, None, is_anchor=True), [])

package/scripts/test_worktree_ignore_seed.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""Consumer ignore-gap contract (#255).
+
+Shipped skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and `ANNAHMEN.md` into a
+session worktree, but `.gitignore` is a consumer file the kit does not own, so
+`init`/`update` never seed the matching rules. ADR 0008 resolves the gap two
+ways, and both are pinned here:
+
+1. `/setup-workflow` may **offer** the rules through
+   `scripts/worktree-lifecycle/ignore_seed.py`. The helper is append-only
+   inside one idempotent marker block: it never rewrites, reorders, or removes
+   an existing line, it is a no-op on re-run, and it is unreachable from
+   `init`/`update` reconciliation.
+2. Shipped skill prose states the assumption instead of asserting the ignore
+   state as a fact the kit cannot guarantee.
+
+Run: python3 scripts/test_worktree_ignore_seed.py
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+LIFECYCLE = REPO / "scripts/worktree-lifecycle"
+HELPER = LIFECYCLE / "ignore_seed.py"
+ARTIFACT_MANIFEST = LIFECYCLE / "plan-artifacts.json"
+SKILL_TREES = (REPO / ".claude/skills", REPO / ".agents/skills")
+
+
+def load_helper():
+    spec = importlib.util.spec_from_file_location("wl_ignore_seed", HELPER)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", *args], cwd=repo, capture_output=True, text=True, check=True,
+    )
+
+
+def make_repo(stack, gitignore: str | None = None) -> Path:
+    repo = Path(stack.enter_context(tempfile.TemporaryDirectory()))
+    git(repo, "init", "-q")
+    git(repo, "config", "user.email", "test@example.com")
+    git(repo, "config", "user.name", "test")
+    if gitignore is not None:
+        (repo / ".gitignore").write_text(gitignore, encoding="utf-8")
+    return repo
+
+
+class ArtifactManifestTest(unittest.TestCase):
+    """The kit declares which planning artifacts its own skills write."""
+
+    def test_manifest_declares_the_three_planning_artifacts(self):
+        document = json.loads(ARTIFACT_MANIFEST.read_text(encoding="utf-8"))
+        paths = [entry["path"] for entry in document["artifacts"]]
+        self.assertEqual(
+            paths, ["PLAN.md", "PLAN-REVIEW-LOG.md", "ANNAHMEN.md"],
+        )
+        for entry in document["artifacts"]:
+            self.assertTrue(entry["writtenBy"], entry["path"])
+
+
+class PlanTest(unittest.TestCase):
+    """`plan()` reports the exact append, never a rewrite."""
+
+    def setUp(self):
+        self.helper = load_helper()
+        self.stack = __import__("contextlib").ExitStack()
+        self.addCleanup(self.stack.close)
+
+    def test_fresh_repo_lists_every_artifact_as_pending(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        plan = self.helper.plan(repo)
+        self.assertEqual(
+            plan.pending, ("PLAN.md", "PLAN-REVIEW-LOG.md", "ANNAHMEN.md"),
+        )
+        self.assertEqual(plan.already_ignored, ())
+        self.assertEqual(plan.status, "append")
+        for path in plan.pending:
+            self.assertIn(f"\n{path}\n", plan.block)
+        self.assertTrue(plan.block.startswith(self.helper.BLOCK_START))
+        self.assertTrue(plan.block.rstrip("\n").endswith(self.helper.BLOCK_END))
+
+    def test_missing_gitignore_is_reported_as_a_create(self):
+        repo = make_repo(self.stack)
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.status, "append")
+        self.assertFalse(plan.gitignore_exists)
+
+    def test_consumer_rules_already_covering_everything_are_nothing_to_do(self):
+        repo = make_repo(
+            self.stack, "PLAN.md\nPLAN-REVIEW-LOG.md\nANNAHMEN.md\n",
+        )
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.pending, ())
+        self.assertEqual(plan.status, "nothing-to-do")
+        self.assertIsNone(plan.block)
+
+    def test_partial_coverage_pends_only_the_missing_rules(self):
+        repo = make_repo(self.stack, "PLAN.md\n")
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.pending, ("PLAN-REVIEW-LOG.md", "ANNAHMEN.md"))
+        self.assertEqual(plan.already_ignored, ("PLAN.md",))
+        self.assertNotIn("\nPLAN.md\n", plan.block)
+
+    def test_a_wildcard_consumer_rule_counts_as_covered(self):
+        repo = make_repo(self.stack, "*.md\n")
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.pending, ())
+
+    def test_a_tracked_artifact_is_named_because_a_rule_cannot_untrack_it(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        (repo / "PLAN.md").write_text("plan\n", encoding="utf-8")
+        git(repo, "add", "PLAN.md")
+        git(repo, "commit", "-qm", "add plan")
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.tracked, ("PLAN.md",))
+        self.assertIn("PLAN.md", plan.pending)
+
+
+class ApplyTest(unittest.TestCase):
+    """`apply()` is append-only, idempotent, and never rewrites."""
+
+    def setUp(self):
+        self.helper = load_helper()
+        self.stack = __import__("contextlib").ExitStack()
+        self.addCleanup(self.stack.close)
+
+    def test_apply_appends_and_preserves_the_existing_bytes_verbatim(self):
+        original = "node_modules/\n\n# my rules\ndist/\n"
+        repo = make_repo(self.stack, original)
+        result = self.helper.apply(repo)
+        self.assertEqual(result.status, "appended")
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        self.assertTrue(text.startswith(original))
+        self.assertIn(self.helper.BLOCK_START, text)
+        for path in ("PLAN.md", "PLAN-REVIEW-LOG.md", "ANNAHMEN.md"):
+            self.assertIn(f"\n{path}\n", text)
+
+    def test_rerun_is_a_byte_identical_no_op(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        self.helper.apply(repo)
+        first = (repo / ".gitignore").read_bytes()
+        second_result = self.helper.apply(repo)
+        self.assertEqual(second_result.status, "nothing-to-do")
+        self.assertEqual((repo / ".gitignore").read_bytes(), first)
+        self.assertEqual(first.decode().count(self.helper.BLOCK_START), 1)
+
+    def test_decline_path_writes_nothing(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        before = (repo / ".gitignore").read_bytes()
+        self.helper.plan(repo)
+        self.assertEqual((repo / ".gitignore").read_bytes(), before)
+
+    def test_already_covered_repo_is_left_untouched(self):
+        original = "PLAN.md\nPLAN-REVIEW-LOG.md\nANNAHMEN.md\n"
+        repo = make_repo(self.stack, original)
+        result = self.helper.apply(repo)
+        self.assertEqual(result.status, "nothing-to-do")
+        self.assertEqual(
+            (repo / ".gitignore").read_text(encoding="utf-8"), original,
+        )
+
+    def test_missing_gitignore_is_created_with_only_the_block(self):
+        repo = make_repo(self.stack)
+        self.helper.apply(repo)
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        self.assertTrue(text.startswith(self.helper.BLOCK_START))
+
+    def test_an_edited_marker_block_blocks_instead_of_rewriting(self):
+        repo = make_repo(self.stack)
+        self.helper.apply(repo)
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        edited = text.replace("ANNAHMEN.md\n", "")
+        (repo / ".gitignore").write_text(edited, encoding="utf-8")
+        result = self.helper.apply(repo)
+        self.assertEqual(result.status, "blocked")
+        self.assertEqual(
+            (repo / ".gitignore").read_text(encoding="utf-8"), edited,
+        )
+        self.assertEqual(edited.count(self.helper.BLOCK_START), 1)
+
+    def test_cli_preview_writes_nothing_and_reports_json(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        before = (repo / ".gitignore").read_bytes()
+        result = subprocess.run(
+            [sys.executable, str(HELPER), "preview", "--repo", str(repo), "--json"],
+            capture_output=True, text=True,
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "append")
+        self.assertEqual((repo / ".gitignore").read_bytes(), before)
+
+    def test_cli_apply_exits_zero_and_is_idempotent(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        for _ in range(2):
+            result = subprocess.run(
+                [sys.executable, str(HELPER), "apply", "--repo", str(repo)],
+                capture_output=True, text=True,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        self.assertEqual(text.count(self.helper.BLOCK_START), 1)
+
+
+class ReconciliationBoundaryTest(unittest.TestCase):
+    """Only setup-workflow may reach the seeder; never init/update."""
+
+    def test_no_installer_command_invokes_the_seeder(self):
+        # bundle.mjs only DECLARES the file as shipped; every other installer
+        # module must not know the seeder exists.
+        declaration = REPO / "src/lib/bundle.mjs"
+        offenders = []
+        for path in sorted((REPO / "src").rglob("*.mjs")):
+            if path == declaration:
+                continue
+            if "ignore_seed" in path.read_text(encoding="utf-8"):
+                offenders.append(str(path.relative_to(REPO)))
+        self.assertEqual(offenders, [])
+
+    def test_the_seeder_ships_with_the_kit(self):
+        bundle = (REPO / "src/lib/bundle.mjs").read_text(encoding="utf-8")
+        self.assertIn("scripts/worktree-lifecycle/ignore_seed.py", bundle)
+        self.assertIn("scripts/worktree-lifecycle/plan-artifacts.json", bundle)
+
+
+class SetupWorkflowOfferTest(unittest.TestCase):
+    """The offer is an explicit, previewed, declinable setup step."""
+
+    def _skill(self, tree: Path) -> str:
+        return (tree / "setup-workflow/SKILL.md").read_text(encoding="utf-8")
+
+    def _seed(self, tree: Path) -> str:
+        return (tree / "setup-workflow/worktree-lifecycle.md").read_text(
+            encoding="utf-8",
+        )
+
+    def test_both_surfaces_document_the_previewed_offer(self):
+        for tree in SKILL_TREES:
+            body = self._skill(tree)
+            self.assertIn(
+                "python3 scripts/worktree-lifecycle/ignore_seed.py preview", body,
+            )
+            self.assertIn(
+                "python3 scripts/worktree-lifecycle/ignore_seed.py apply", body,
+            )
+            flat = re.sub(r"\s+", " ", body)
+            self.assertIn("Add the rules", flat)
+            self.assertIn("Not now", flat)
+
+    def test_the_seed_contract_carries_the_ignore_offer_matrix(self):
+        for tree in SKILL_TREES:
+            flat = re.sub(r"\s+", " ", self._seed(tree))
+            self.assertIn("ignore_seed.py", flat)
+            for row in ("approve", "decline", "already ignored", "re-run"):
+                self.assertIn(row, flat)
+
+
+class ProseClaimCensusTest(unittest.TestCase):
+    """No shipped skill asserts an ignore state the kit cannot guarantee."""
+
+    ARTIFACT = re.compile(
+        r"PLAN\.md|PLAN-REVIEW-LOG\.md|ANNAHMEN\.md|plan doc|assumptions log",
+        re.IGNORECASE,
+    )
+    # Unconditional assertions of the ignore state. Conditional or hedged
+    # wording ("a project may gitignore these files", "when `PLAN.md` is
+    # ignored") is deliberately allowed.
+    FORBIDDEN = (
+        re.compile(r"\(gitignored\b", re.IGNORECASE),
+        re.compile(r"\b(?:is|are|stays?|remains?)\s+gitignored\b", re.IGNORECASE),
+        re.compile(r"\bgitignored\s+(?:at|in|since)\b", re.IGNORECASE),
+        re.compile(r"\ba\s+gitignored\s+plan\s+doc\b", re.IGNORECASE),
+        re.compile(r"\bgitignored,\s*on-disk only\b", re.IGNORECASE),
+    )
+    WINDOW = 160
+
+    def _claim_offenders(self):
+        offenders = []
+        for tree in SKILL_TREES:
+            for path in sorted(tree.rglob("*.md")):
+                flat = re.sub(r"\s+", " ", path.read_text(encoding="utf-8"))
+                for pattern in self.FORBIDDEN:
+                    for match in pattern.finditer(flat):
+                        window = flat[
+                            max(0, match.start() - self.WINDOW):
+                            match.end() + self.WINDOW
+                        ]
+                        if self.ARTIFACT.search(window):
+                            offenders.append(
+                                f"{path.relative_to(REPO)}: {match.group(0)}"
+                            )
+        return sorted(set(offenders))
+
+    def test_no_skill_states_the_ignore_rule_as_an_installed_fact(self):
+        self.assertEqual(self._claim_offenders(), [])
+
+    def test_the_replacement_wording_names_who_can_make_it_true(self):
+        for name in ("grill-me", "grill-with-docs", "orchestrate-wave"):
+            for tree in SKILL_TREES:
+                body = (tree / name / "SKILL.md").read_text(encoding="utf-8")
+                flat = re.sub(r"\s+", " ", body)
+                self.assertIn("setup-workflow", flat, f"{tree}/{name}")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/worktree-lifecycle/README.md

@@ -58,6 +58,24 @@ the core proves the target is unsafe.
 | `enforce-worktree-discipline.py` | PreToolUse | routes issue-branch creation through the configured setup entry |
 | `slice-handoff-hint.py` | UserPromptSubmit | names the configured setup entry for a defined slice |
 
+## Planning-artifact ignore rules
+
+`plan-artifacts.json` is the kit-owned declaration of the planning artefacts the
+shipped skills write (`PLAN.md`, `PLAN-REVIEW-LOG.md`, `ANNAHMEN.md`).
+`ignore_seed.py` turns that declaration into an offer, never an installation:
+`preview` reports what an approval would append and writes nothing, and `apply`
+appends exactly one marker block. `.gitignore` is a consumer file the kit does
+not own, so only an explicit approved `/setup-workflow` step may run `apply`;
+`init` and `update` reconciliation never reach it (ADR 0008).
+
+The append never rewrites, reorders, or removes an existing line. A repository
+that already ignores every artefact reports `nothing-to-do`, a re-run after an
+approval is a byte-identical no-op, and a marker block the consumer has since
+edited reports `blocked` rather than being repaired. An artefact already tracked
+in git is named separately — an ignore rule cannot untrack it, and the helper
+never runs `git rm`. Only after such an approval does the `scratchPatterns`
+derivation have real ignored planning artefacts to read.
+
 ## Cleanup
 
 `cleanup.py` previews by default. Removal refuses protected, tracked-dirty,