@ikon85/agent-workflow-kit 0.40.0 → 0.41.1

package/README.md

@@ -469,6 +469,24 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.41.1
+
+- changed: `README.md`
+- changed: `agent-workflow-kit.package.json`
+- changed: `package.json`
+- changed: `scripts/pr-body-check.py`
+- changed: `scripts/test_pr_body_check.py`
+- changed: `scripts/test_worktree_wrapup_contract.py`
+- changed: `scripts/wrapup-land.py`
+
+### 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.1",
   "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": "d18a9f1bf9285506bd7d40a1800dd9b66f631bd4666f0ae801e8db1882d3ad2d",
       "mode": 493,
       "origin": "kit"
     },
@@ -2867,7 +2867,7 @@
       "path": "scripts/wrapup-land.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "476012558bb786070ce47458c6f0734ff110d5d957af72e13b20d49a37a03592",
+      "sha256": "de41f6c7bee1f67f3f25db4c7750a3caca422be5749012c6d5402cfeed91b2f7",
       "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.1",
   "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

@@ -125,6 +125,21 @@ def _close_on(body: str, n: int) -> bool:
     return bool(pat.search(strip_code(body)))
 
 
+def active_close_targets(body: str) -> list:
+    """All issue numbers an ACTIVE close-keyword targets (outside code spans),
+    as sorted, deduplicated strings. Same grammar `_close_on` enforces —
+    plain `closes #n`, the colon form, and the full-URL form. This is the one
+    close grammar; close-verification (wrapup-land Step 5b) must derive its
+    targets from here, never from a branch number."""
+    text = strip_code(body)
+    pat = re.compile(
+        rf"\b(?:{CLOSE_KEYWORDS})(?::\s*|\s+)"
+        rf"(?:#0*(\d+)(?!\d)|https?://\S+/issues/0*(\d+)(?!\d))",
+        re.IGNORECASE)
+    found = {a or b for a, b in pat.findall(text)}
+    return sorted(found, key=int)
+
+
 def _part_of(body: str, n: int) -> bool:
     return bool(re.search(
         rf"\b{PART_OF_RE_SRC}(?::\s*|\s+)#0*{n}(?!\d)", body or "", re.IGNORECASE))
@@ -208,13 +223,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,25 @@ 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_active_close_targets_extracts_all_forms(self):
+        body = ("closes #12\nFixes: #13\n"
+                "resolves https://github.com/iKon85/agent-workflow-kit/issues/14\n"
+                "`closes #99` and Part of #320 and closes #12")
+        self.assertEqual(pbc.active_close_targets(body), ["12", "13", "14"])
+
+    def test_active_close_targets_empty_for_part_of_only(self):
+        self.assertEqual(pbc.active_close_targets("Part of #320\n**Retro:** skipped — x"), [])
+
+    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_wrapup_contract.py

@@ -251,6 +251,13 @@ def downgrade_landing_attempt_to_v1(core, worktree: Path) -> Path:
 
 
 class WorktreeCleanupContract(unittest.TestCase):
+    def test_declared_close_targets_is_pr_body_authority(self):
+        mod = load_wrapup()
+        self.assertEqual(mod.declared_close_targets("Part of #320"), [])
+        self.assertEqual(mod.declared_close_targets("closes #341\ncloses #12"),
+                         ["12", "341"])
+        self.assertEqual(mod.declared_close_targets("`closes #341`"), [])
+
     def test_profile_scratch_and_generated_evidence_share_safe_removal_contract(self):
         wrapup = load_wrapup()
         with tempfile.TemporaryDirectory() as tmp:

package/scripts/wrapup-land.py

@@ -423,6 +423,18 @@ def issue_from_branch(branch: str) -> str | None:
     return m.group(2) if m else None
 
 
+def declared_close_targets(body: str) -> list:
+    """Close authority for Step 5b: the PR body's ACTIVE close keywords, parsed
+    by pr-body-check's one close grammar. A branch number is context, never
+    closure authority — branch-derived closing once shut a Program-PRD that a
+    PR deliberately referenced only via `Part of`."""
+    spec = importlib.util.spec_from_file_location(
+        "pr_body_check_grammar", Path(__file__).parent / "pr-body-check.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod.active_close_targets(body)
+
+
 def load_profile() -> dict:
     try:
         from board_config import load_board_config
@@ -1245,16 +1257,26 @@ def cmd_land(args) -> dict:
     elif p.returncode != 0:
         report["warnings"].append(f"branch -d {branch} refused: {(p.stderr or '').strip()[:200]}")
 
-    # Step 5b — verify issue auto-close (backtick-swallowed `closes` misses)
+    # Step 5b — verify declared auto-closes (backtick-swallowed `closes`
+    # misses). Targets come from the merged PR body's close keywords, never
+    # from the branch number.
     issue = issue_from_branch(branch)
-    if issue:
-        p = run(["gh", "issue", "view", issue, "--json", "state"])
-        if p.returncode == 0 and json.loads(p.stdout)["state"] == "OPEN":
-            run(["gh", "issue", "close", issue, "-c",
-                 f"Merged via PR #{pr} — auto-close didn't fire; closed manually."])
-            report["issue_close"] = f"#{issue} closed manually"
-        elif p.returncode == 0:
-            report["issue_close"] = f"#{issue} already closed"
+    p = run(["gh", "pr", "view", pr, "--json", "body"])
+    merged_body = (json.loads(p.stdout).get("body") or "") if p.returncode == 0 else ""
+    targets = declared_close_targets(merged_body)
+    if not targets:
+        report["issue_close"] = "no close targets declared — nothing to verify"
+    else:
+        states = []
+        for t in targets:
+            q = run(["gh", "issue", "view", t, "--json", "state"])
+            if q.returncode == 0 and json.loads(q.stdout)["state"] == "OPEN":
+                run(["gh", "issue", "close", t, "-c",
+                     f"Merged via PR #{pr} — auto-close didn't fire; closed manually."])
+                states.append(f"#{t} closed manually")
+            elif q.returncode == 0:
+                states.append(f"#{t} already closed")
+        report["issue_close"] = " · ".join(states)
 
     # Step 5c — local merged-branch sweep (-d only: unreachable-from-main is refused)
     swept = []