@ikon85/agent-workflow-kit 0.40.0 → 0.41.0

package/README.md

@@ -469,6 +469,14 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.41.0
+
+- added: `docs/adr/0009-teardown-authority-is-stateless-repository-classification.md`
+- changed: `agent-workflow-kit.package.json`
+- changed: `docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md`
+- changed: `scripts/pr-body-check.py`
+- changed: `scripts/test_pr_body_check.py`
+
 ### 0.40.0 — planning ignore rules are offered, never installed
 
 Nothing in this release requires a consumer action. `kit-update` reconciles it.

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.40.0",
+  "kitVersion": "0.41.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -2627,7 +2627,7 @@
       "path": "scripts/pr-body-check.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "864dad50be7904cf0c1d70956352c70d2195a350a5a6875de6b866c494f16612",
+      "sha256": "7fa67a672d6f6986b0fba99e78157d51225ab91f61b691a4cc184d316b521882",
       "mode": 493,
       "origin": "kit"
     },

package/docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md

@@ -1,6 +1,6 @@
 # Session teardown requires provenance-bound ownership
 
-Status: accepted (2026-07-26, Wave #271)
+Status: superseded by [ADR-0009](./0009-teardown-authority-is-stateless-repository-classification.md) (2026-07-27, #320)
 
 Long agent sessions create branches, linked worktrees, setup outputs, and
 landing-time build artifacts. The desired end state is that every

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.40.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), [])