@ikon85/agent-workflow-kit 0.37.0 → 0.39.0

package/scripts/workflow-advisories/core.py

@@ -1,13 +1,37 @@
 """Profile-driven decision core for non-blocking Workflow Advisories."""
 from __future__ import annotations
 
-import fnmatch
+import importlib.util
 import json
 import re
 import subprocess
+import sys
 from dataclasses import dataclass
 from pathlib import Path
 
+PROFILE_GLOBS_MODULE = "_agent_workflow_kit_profile_globs"
+
+
+def load_profile_globs():
+    """Load the one shared repository-relative glob dialect exactly once."""
+    module = sys.modules.get(PROFILE_GLOBS_MODULE)
+    if module is not None:
+        return module
+    path = Path(__file__).resolve().parents[1] / "profile_globs.py"
+    spec = importlib.util.spec_from_file_location(PROFILE_GLOBS_MODULE, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load the shared profile glob dialect from {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[PROFILE_GLOBS_MODULE] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+# Consumer profile globs are matched here exactly as Worktree Lifecycle matches
+# its own: one dialect, so an advisory and a deletion decision can never
+# disagree about which repository-relative paths a pattern selects.
+path_glob_matches = load_profile_globs().path_glob_matches
+
 
 @dataclass(frozen=True)
 class Decision:
@@ -87,7 +111,8 @@ def baseline_decision(profile: dict, payload: dict, root: Path, branch: str) ->
     raw_path = payload.get("tool_input", {}).get("file_path")
     relative = _repo_relative(root, raw_path) if raw_path else None
     if not relative or not any(
-        fnmatch.fnmatch(relative, pattern) for pattern in config.get("sourceGlobs", [])
+        path_glob_matches(relative, pattern)
+        for pattern in config.get("sourceGlobs", [])
     ):
         return Decision(None, "PreToolUse")
     manifest = root / config.get("manifestPath", ".agent/baseline.json")
@@ -119,7 +144,7 @@ def pre_refactor_decision(profile: dict, payload: dict, root: Path) -> Decision:
     seen: set[tuple[str, ...]] = set()
     for surface in config.get("surfaces", []):
         if not any(
-            fnmatch.fnmatch(path, pattern)
+            path_glob_matches(path, pattern)
             for path in changed
             for pattern in surface.get("globs", [])
         ):
@@ -170,7 +195,7 @@ def stop_check_decision(profile: dict, payload: dict, root: Path) -> Decision:
     seen: set[tuple[str, ...]] = set()
     for surface in config.get("surfaces", []):
         if not any(
-            fnmatch.fnmatch(path, pattern)
+            path_glob_matches(path, pattern)
             for path in changed
             for pattern in surface.get("globs", [])
         ):

package/scripts/worktree-lifecycle/README.md

@@ -19,6 +19,29 @@ they do not carry a second branch regex, worktree traversal, or failure policy.
 - `riskyCommandPatterns`: commands that must target the active linked worktree.
 - `scratchPatterns`: consumer-owned glob patterns for untracked disposable
   planning artefacts. No filename is assumed by Core.
+- `wrapup.landingGeneratedArtifactPatterns`: an explicitly reviewed
+  consumer-owned allowlist for outputs created by the landing commands. It is
+  deletion authority, so setup never derives it from `.gitignore` alone and
+  update never installs a universal default.
+
+Profile globs use one repository-relative POSIX dialect, implemented once in
+`scripts/profile_globs.py` and loaded by this core and by
+`scripts/workflow-advisories/core.py`. `*` and `?` stay inside one path
+segment; `[seq]`/`[!seq]` are per-segment character classes; `**` as a whole
+segment matches zero or more segments, so a leading `**/` also matches the
+repository root and `dir/**` also matches `dir` itself; matching is always
+case-sensitive on every host filesystem; and a pattern must match the whole
+path. For example, `**/__pycache__/**` matches both root and nested caches,
+while `dist-kit/*` does not match `dist-kit/a/b`.
+
+Because both capabilities load the same matcher, a pattern can never select one
+set of paths for an advisory and a different set for a deletion decision. Run
+`python3 scripts/profile_globs.py <profile.json>` to review an installed
+profile: it names every pattern whose match set narrows or widens against that
+key's legacy matcher, prints the witness path proving it, marks the keys that
+carry deletion authority, and exits 1 when anything needs review. It reads the
+profile and never rewrites a pattern, so a migration cannot silently expand
+cleanup authority.
 
 Unknown or malformed events fail open without changing repository state.
 Security-sensitive, profile-matched edits and commands fail closed only when
@@ -49,11 +72,127 @@ same removable inventory, deletes only the exact contained regular scratch
 files from that inventory, and uses ordinary `git worktree remove`. It never
 bypasses Git's final concurrent-change check with force removal.
 
+The generic setup route atomically records its ignored and complete
+untracked-file inventories in the linked worktree's Git metadata after its
+configured setup steps. The record is bound to the worktree path, branch, root
+device/inode, and setup HEAD, and carries a canonical digest. Existing
+worktrees can receive a conservative baseline only when they are the exact
+registered no-follow directory on an attached branch with a clean tracked
+worktree and index. Setup reuse defers that backfill, without blocking the
+existing worktree, while tracked work is dirty or landing-generated blockers
+are present. Landing classifies those blockers before writing any baseline;
+after they are moved, every remaining current ignored and untracked path is
+recorded as pre-existing and therefore protected. A corrupt baseline or an
+active landing attempt is never overwritten. The claim-bound session route
+below captures its stricter baseline before project setup so a failed setup has
+an exact recovery boundary.
+
+Before merge, the committed worktree profile may only nominate exact,
+identity-bound landing candidates; it authorizes no deletion. After merge and
+`fetch origin/main`, cleanup reloads the profile directly from canonical
+`origin/main`, requires its scratch and generator policies to equal the
+worktree candidate and the policy digest frozen at attempt start, and only then
+authorizes mutation. Every supplied generator-evidence path is independently
+checked against that canonical generator policy. A missing policy is distinct
+from an explicit empty policy. An unmerged or transient branch policy therefore
+cannot grant itself broader cleanup authority.
+
+Canonical policy that drifts between attempt start and post-merge cleanup keeps
+that refusal, and the refusal names its supported recovery. Recovery re-derives
+authority from the merged canonical policy alone: it never consults the stale
+worktree candidate, never re-scans for new candidates, requires the branch to
+already be an ancestor of canonical main, and requires each frozen identity to
+be both named by canonical policy and unchanged on disk. Evidence outside
+canonical policy, a changed identity, and pre-existing or foreign state stop the
+recovery instead of being deleted, and a repeated run after a completed teardown
+is a no-op.
+
+The landing adapter may carry exact scratch evidence only for current ignored
+files that match the consumer-owned
+`wrapup.landingGeneratedArtifactPatterns` profile and were absent from that
+creation baseline. Missing, changed, or incoherent provenance stops landing
+cleanup. Initial/profile-matched files, unmatched files, symlinks, and writes
+after the landing evidence snapshot remain cleanup stops; deletion still uses
+the same descriptor-bound regular-file primitive and a second inventory check.
+Mutable session logs belong in explicit `scratchPatterns`, not in the landing
+generator allowlist: their identity is frozen at final cleanup assessment, so
+normal logging before teardown remains live while a later append or replacement
+still stops deletion.
+Landing-start blockers are classified before a journal is written, so moving a
+protected blocker permits a clean next attempt. An explicit relinquish archives
+either a started or frozen attempt, including drifted evidence, without
+deleting or claiming any file; the next preflight treats every current file as
+pre-existing. Exact unchanged frozen evidence remains directly resumable. The
+attempt journal name is classified without following a symlink, so a symlinked
+or dangling journal entry stops instead of being read or replaced, and each
+archived receipt is filed under a contract-version-neutral stem plus its own
+recorded contract version. A journal written under a superseded contract is
+classified as legacy rather than corrupt when it still satisfies its own
+recorded contract; that refusal names the archive route explicitly, while a
+journal that fails its own contract is still reported as incoherent evidence.
+
 `cleanup.py sweep` is the read-only inventory entrypoint. It accounts once for
 every linked worktree and local branch, reports issue/PR/merge/age/removal
 facts, and counts merged remote branches separately. It never removes a
 worktree or branch.
 
+## Session-owned teardown
+
+`session.py` is the narrower orchestration route. It binds one receipt in the
+Git common directory to the active `wave-active/<anchor>` annotated claim:
+
+```sh
+python3 scripts/worktree-lifecycle/session.py begin --anchor <n> --owner <run> --base <wave-head>
+python3 scripts/worktree-lifecycle/session.py create --anchor <n> --owner <run> --base <current-wave-head> <issue> <slug> <type>
+python3 scripts/worktree-lifecycle/session.py recover --anchor <n> --owner <run> --branch <exact-branch>
+python3 scripts/worktree-lifecycle/session.py seal --anchor <n> --owner <run>
+python3 scripts/worktree-lifecycle/session.py inspect --anchor <n> --owner <run> --main origin/main
+python3 scripts/worktree-lifecycle/session.py teardown --anchor <n> --owner <run> --main origin/main
+```
+
+Only `create` can add an inventory row, and it refuses any branch or path that
+already existed. It journals a provisional exact row before `git worktree add`,
+then captures the shared artifact baseline before project setup and promotes
+the row only after setup succeeds. Session inspection
+therefore accepts generated scratch only when the exact path matches the
+profile and is absent from the creation baseline; missing, changed, or
+incoherent provenance stops. `seal` records the final exact branch OIDs.
+Inspection reports ancestry, one-to-one stable patch equivalence, unique
+content, and ambiguity separately. Empty commits, non-ancestry merge commits,
+duplicate patch IDs, open or unreadable PR evidence, dirt, protected names,
+stale registrations, recreated removed targets, and identity drift stop the
+whole teardown before mutation.
+
+If setup fails, the provisional row becomes `recovery-pending`. Automatic and
+explicit `recover` use the same bounded route: active claim and receipt,
+protected name, PR state, exact ref OID, registration/root identity, and the
+creation baseline are revalidated. A branch-only remainder is compare-deleted
+only at its provisional OID. A registered worktree whose add succeeded before
+root journaling is adopted only when its Git registration/backlink, branch,
+OID, and exact-clean inventory all match.
+
+For failed project setup, exact index/worktree diff hashes and paths are frozen
+without storing diff content. Exact regular-file or no-follow symlink identity
+is frozen for every setup-created untracked path. Recovery revalidates that
+evidence, restores only the frozen tracked paths to the creation OID, and
+unlinks only matching untracked identities; later foreign files,
+modifications, or replacements stop without losing receipt ownership. If
+identity capture cannot finish, the receipt retains only a bounded failure
+class and can retry from the unchanged inventory or an exact-clean worktree.
+Raw command, exception, stdout, and stderr text is never retained or archived.
+Recovery uses ordinary worktree removal and compare-deletes the exact ref.
+
+Teardown re-runs that complete assessment, archives every recovery OID in the
+receipt before its first mutation, and revalidates canonical main, the active
+claim and receipt, profile protection, PR state, branch OID, worktree
+registration/root identity, dirt, and the exact scratch inventory immediately
+before each target mutation. After ordinary worktree removal it rechecks the
+ref-side gates, then compare-deletes only the recorded local refs with
+`git update-ref -d <ref> <expected-oid>`. A concurrent ref move therefore
+survives, while a partial run keeps its recovery OIDs and can resume. Generic
+cleanup and sweep never consume this ownership route and never infer authority
+over a foreign branch.
+
 Claude hook wiring and any Codex adaptation consume this same profile and core.
 An adapter may change only the surface event envelope; it must preserve the
 core verdict and message.

package/scripts/worktree-lifecycle/capabilities.json

@@ -39,7 +39,15 @@
     {
       "historicalPath": "scripts/cleanup-worktrees.sh",
       "artifact": "scripts/worktree-lifecycle/cleanup.py",
-      "primitives": ["profile", "git-facts", "cleanup-safety"]
+      "supportingArtifacts": ["scripts/worktree-lifecycle/session.py"],
+      "primitives": [
+        "profile",
+        "git-facts",
+        "cleanup-safety",
+        "claim-bound-session-receipt",
+        "patch-equivalence",
+        "compare-and-delete"
+      ]
     }
   ]
 }

package/scripts/worktree-lifecycle/cleanup.py

@@ -4,22 +4,22 @@
 from __future__ import annotations
 
 import argparse
-from contextlib import contextmanager
 from dataclasses import asdict, replace
 import json
-import os
-import stat
 import sys
-from pathlib import Path, PurePosixPath
+from pathlib import Path
 
 from core import (
     LifecycleError,
+    bind_cleanup_scratch_evidence,
     classify_cleanup,
     collect_cleanup_facts,
     collect_sweep,
     load_profile,
     main_worktree,
+    remove_authorized_scratch,
     run,
+    verified_worktree_root,
 )
 
 
@@ -75,52 +75,18 @@ def collect_assessment(profile, main: Path, worktree: Path, gh_command: str):
         worktree,
     )
     state = pr_state(gh_command, main, facts.branch)
-    return classify_cleanup(profile, replace(facts, pr_state=state))
-
-
-@contextmanager
-def verified_worktree_root(root: Path, expected_device: int, expected_inode: int):
-    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
-    no_follow = getattr(os, "O_NOFOLLOW", 0)
-    descriptor = None
+    assessment = classify_cleanup(profile, replace(facts, pr_state=state))
     try:
-        descriptor = os.open(root, directory_flags | no_follow)
-        metadata = os.fstat(descriptor)
-        if (metadata.st_dev, metadata.st_ino) != (expected_device, expected_inode):
-            raise LifecycleError("worktree root changed before removal")
-        yield descriptor
-    except OSError as error:
-        raise LifecycleError("worktree root changed before removal") from error
-    finally:
-        if descriptor is not None:
-            os.close(descriptor)
-
-
-def remove_contained_regular(root_descriptor: int, relative: str) -> None:
-    path = PurePosixPath(relative)
-    if path.is_absolute() or not path.parts or any(part in {"", ".", ".."} for part in path.parts):
-        raise LifecycleError(f"unsafe scratch path: {relative}")
-    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
-    no_follow = getattr(os, "O_NOFOLLOW", 0)
-    descriptors = []
-    try:
-        current = root_descriptor
-        for component in path.parts[:-1]:
-            current = os.open(
-                component,
-                directory_flags | no_follow,
-                dir_fd=current,
-            )
-            descriptors.append(current)
-        metadata = os.stat(path.name, dir_fd=current, follow_symlinks=False)
-        if not stat.S_ISREG(metadata.st_mode):
-            raise LifecycleError(f"scratch path is not a regular file: {relative}")
-        os.unlink(path.name, dir_fd=current)
-    except OSError as error:
-        raise LifecycleError(f"scratch path changed before removal: {relative}") from error
-    finally:
-        for descriptor in reversed(descriptors):
-            os.close(descriptor)
+        return bind_cleanup_scratch_evidence(
+            profile,
+            assessment,
+            require_generator_evidence=True,
+        )
+    except LifecycleError as error:
+        return replace(
+            assessment,
+            reasons=assessment.reasons + (f"scratch evidence stop: {error}",),
+        )
 
 
 def execute(args: argparse.Namespace) -> dict:
@@ -155,6 +121,7 @@ def execute(args: argparse.Namespace) -> dict:
         or latest.assumptions != assessment.assumptions
         or latest.root_device != assessment.root_device
         or latest.root_inode != assessment.root_inode
+        or latest.scratch_evidence != assessment.scratch_evidence
     ):
         raise LifecycleError("cleanup changed before removal: inventory no longer matches preview")
     with verified_worktree_root(
@@ -162,8 +129,12 @@ def execute(args: argparse.Namespace) -> dict:
         latest.root_device,
         latest.root_inode,
     ) as root_descriptor:
-        for scratch in latest.scratch_files:
-            remove_contained_regular(root_descriptor, scratch)
+        remove_authorized_scratch(
+            profile,
+            root_descriptor,
+            latest.scratch_files,
+            assessment.scratch_evidence,
+        )
     run(["git", "worktree", "remove", str(latest.worktree)], cwd=main)
     run(["git", "branch", "-d", assessment.branch], cwd=main)
     report["removed"] = True