@ikon85/agent-workflow-kit 0.38.0 → 0.40.0

package/scripts/worktree-lifecycle/README.md

@@ -24,11 +24,25 @@ they do not carry a second branch regex, worktree traversal, or failure policy.
   deletion authority, so setup never derives it from `.gitignore` alone and
   update never installs a universal default.
 
-Profile globs use repository-relative POSIX semantics. `*` stays inside one
-path segment; `**` crosses `/`, and leading `**/` also matches the repository
-root. For example, `**/__pycache__/**` matches both root and nested caches,
+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
 the core proves the target is unsafe.
@@ -44,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,
@@ -83,6 +115,16 @@ 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
@@ -98,7 +140,14 @@ 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.
+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

package/scripts/worktree-lifecycle/core.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
+import importlib.util
 import json
 import os
 import re
 import stat
+import sys
 from contextlib import contextmanager
 from dataclasses import dataclass, replace
-from fnmatch import fnmatchcase
 from hashlib import sha256
 from pathlib import Path, PurePosixPath
 from time import time
@@ -29,12 +30,50 @@ _BRANCH_CHANGE_RE = re.compile(r"\b(?:git\s+(?:checkout|switch)|gh\s+pr\s+(?:mer
 _BRANCH_CREATE_RE = re.compile(r"\bgit\s+(?:checkout|switch)\s+-[bc]\s+(\S+)")
 ARTIFACT_BASELINE_FILE = "awkit-artifact-baseline-v1.json"
 LANDING_ATTEMPT_FILE = "awkit-landing-attempt-v1.json"
+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 Workflow Advisories
+# 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
+
+# Archived receipts are named from a contract-version-neutral stem plus the
+# archived receipt's own contractVersion, so a v2 receipt is never filed as v1.
+LANDING_ATTEMPT_ARCHIVE_STEM = "awkit-landing-attempt"
+LANDING_ATTEMPT_CONTRACT_VERSION = 2
+LANDING_ATTEMPT_KEYS = (
+    "contractVersion", "worktree", "branch", "rootDevice",
+    "rootInode", "baselineDigest", "generatedFiles",
+    "generatedEvidence", "state", "authorizedEvidence",
+    "pushSucceeded",
+)
+ABANDON_ATTEMPT_FLAG = "--abandon-unfinished-attempt"
 
 
 class BaselineBackfillDeferred(LifecycleError):
     """A safe legacy baseline cannot be captured until consumer state changes."""
 
 
+class LegacyLandingAttempt(LifecycleError):
+    """A coherent attempt journal predates the active contract and is not adoptable."""
+
+
 def durable_atomic_json(
     path: Path,
     document: dict[str, Any],
@@ -88,34 +127,6 @@ def durable_replace(source: Path, destination: Path, *, label: str) -> None:
         raise LifecycleError(f"cannot {label}: {error}") from error
 
 
-def path_glob_matches(path: str, pattern: str) -> bool:
-    """Match POSIX path segments while retaining fnmatch bracket compatibility."""
-    path_parts = PurePosixPath(path).parts
-    pattern_parts = PurePosixPath(pattern).parts
-    memo: dict[tuple[int, int], bool] = {}
-
-    def matches(path_index: int, pattern_index: int) -> bool:
-        key = (path_index, pattern_index)
-        if key in memo:
-            return memo[key]
-        if pattern_index == len(pattern_parts):
-            result = path_index == len(path_parts)
-        elif pattern_parts[pattern_index] == "**":
-            result = matches(path_index, pattern_index + 1) or (
-                path_index < len(path_parts)
-                and matches(path_index + 1, pattern_index)
-            )
-        else:
-            result = (
-                path_index < len(path_parts)
-                and fnmatchcase(path_parts[path_index], pattern_parts[pattern_index])
-                and matches(path_index + 1, pattern_index + 1)
-            )
-        memo[key] = result
-        return result
-
-    return matches(0, 0)
-
 @dataclass(frozen=True)
 class RepoFacts:
     root: Path
@@ -209,6 +220,30 @@ def artifact_baseline_path(worktree: Path) -> Path:
     return git_dir / ARTIFACT_BASELINE_FILE
 
 
+def landing_attempt_path(worktree: Path) -> Path:
+    """Return the one landing-attempt journal path beside the artifact baseline."""
+    return artifact_baseline_path(worktree).with_name(LANDING_ATTEMPT_FILE)
+
+
+def landing_attempt_exists(path: Path) -> bool:
+    """Classify journal presence without following a symlink at that name."""
+    return os.path.lexists(path)
+
+
+def require_regular_landing_attempt(path: Path) -> None:
+    """Refuse a journal name occupied by a symlink or any non-regular entry."""
+    if path.is_symlink() or not path.is_file():
+        raise LifecycleError("landing-attempt provenance is not a regular file")
+
+
+def landing_attempt_keys(contract_version: Any) -> list[str]:
+    """Return the exact journal key set recorded by one contract version."""
+    keys = list(LANDING_ATTEMPT_KEYS)
+    if contract_version == LANDING_ATTEMPT_CONTRACT_VERSION:
+        keys.append("policyDigest")
+    return keys
+
+
 def _baseline_payload(
     *,
     worktree: Path,
@@ -395,8 +430,7 @@ def ensure_artifact_baseline(
     path = artifact_baseline_path(worktree)
     if os.path.lexists(path):
         return load_artifact_baseline(worktree)
-    attempt_path = path.with_name(LANDING_ATTEMPT_FILE)
-    if os.path.lexists(attempt_path):
+    if landing_attempt_exists(landing_attempt_path(worktree)):
         raise LifecycleError(
             "artifact provenance baseline is missing while a landing attempt exists"
         )
@@ -447,6 +481,36 @@ def verified_landing_scratch_files(
     )
 
 
+def _classify_superseded_landing_attempt(
+    payload: dict[str, Any],
+    digest: Any,
+    baseline: ArtifactBaseline,
+    worktree: Path,
+) -> None:
+    """Separate a coherent pre-upgrade journal from genuinely corrupt evidence.
+
+    A journal written before the active contract can never be adopted, but it is
+    not damage: it has an exact, non-deleting route out. Only evidence that also
+    fails its own recorded contract is reported as corruption.
+    """
+    if (
+        payload["contractVersion"] != 1
+        or payload["worktree"] != str(worktree.resolve())
+        or payload["branch"] != baseline.branch
+        or (payload["rootDevice"], payload["rootInode"])
+        != (baseline.root_device, baseline.root_inode)
+        or payload["state"] not in {"started", "frozen"}
+        or digest != _baseline_digest(payload)
+    ):
+        raise LifecycleError("landing-attempt provenance is incoherent")
+    raise LegacyLandingAttempt(
+        "landing attempt was started under the superseded v1 journal contract "
+        "and cannot be adopted; archive it with "
+        f"`land {ABANDON_ATTEMPT_FLAG}` — that deletes and claims no file — "
+        "then rerun land"
+    )
+
+
 def landing_start_artifact_inventory(
     profile: WorktreeProfile,
     worktree: Path,
@@ -456,31 +520,32 @@ def landing_start_artifact_inventory(
         worktree,
         reject_ignored_patterns=profile.landing_generated_artifact_patterns,
     )
-    path = artifact_baseline_path(worktree).with_name(LANDING_ATTEMPT_FILE)
-    if path.exists():
+    attempt_path = landing_attempt_path(worktree)
+    if landing_attempt_exists(attempt_path):
+        require_regular_landing_attempt(attempt_path)
         try:
-            document = json.loads(path.read_text(encoding="utf-8"))
+            document = json.loads(attempt_path.read_text(encoding="utf-8"))
+            contract_version = document["contractVersion"]
             payload = {
                 key: document[key]
-                for key in (
-                    "contractVersion", "worktree", "branch", "rootDevice",
-                    "rootInode", "baselineDigest", "generatedFiles",
-                    "generatedEvidence", "state", "authorizedEvidence",
-                    "pushSucceeded", "policyDigest",
-                )
+                for key in landing_attempt_keys(contract_version)
             }
             digest = document["sha256"]
         except (OSError, json.JSONDecodeError, KeyError, TypeError) as error:
             raise LifecycleError(
                 f"landing-attempt provenance is incoherent: {error}"
             ) from error
+        if contract_version != LANDING_ATTEMPT_CONTRACT_VERSION:
+            _classify_superseded_landing_attempt(
+                payload, digest, baseline, worktree
+            )
         if payload["policyDigest"] != landing_cleanup_policy_digest(profile):
             raise LifecycleError(
                 "landing cleanup policy changed after attempt start; "
                 "abandon the unfinished attempt before retrying"
             )
         if (
-            payload["contractVersion"] != 2
+            payload["contractVersion"] != LANDING_ATTEMPT_CONTRACT_VERSION
             or payload["worktree"] != str(worktree.resolve())
             or payload["branch"] != baseline.branch
             or (payload["rootDevice"], payload["rootInode"])
@@ -528,7 +593,7 @@ def landing_start_artifact_inventory(
         "policyDigest": landing_cleanup_policy_digest(profile),
     }
     payload = {
-        "contractVersion": 2,
+        "contractVersion": LANDING_ATTEMPT_CONTRACT_VERSION,
         "worktree": str(worktree.resolve()),
         "branch": baseline.branch,
         "rootDevice": baseline.root_device,
@@ -537,7 +602,7 @@ def landing_start_artifact_inventory(
     }
     digest = _baseline_digest(payload)
     durable_atomic_json(
-        path,
+        attempt_path,
         {**payload, "sha256": digest},
         label="persist landing-attempt provenance",
     )
@@ -620,7 +685,7 @@ def freeze_landing_artifact_evidence(
         )
     if attempt["state"] == "frozen":
         return frozen
-    path = artifact_baseline_path(worktree).with_name(LANDING_ATTEMPT_FILE)
+    path = landing_attempt_path(worktree)
     document = json.loads(path.read_text(encoding="utf-8"))
     payload = {
         key: document[key]
@@ -652,7 +717,7 @@ def reopen_frozen_landing_attempt(
     frozen = freeze_landing_artifact_evidence(
         profile, worktree, push_succeeded=False
     )
-    path = artifact_baseline_path(worktree).with_name(LANDING_ATTEMPT_FILE)
+    path = landing_attempt_path(worktree)
     document = json.loads(path.read_text(encoding="utf-8"))
     payload = {
         key: document[key]
@@ -680,25 +745,15 @@ def abandon_unfinished_landing_attempt(
     worktree: Path,
 ) -> Path:
     """Archive an ambiguous started attempt without claiming or deleting files."""
-    path = artifact_baseline_path(worktree).with_name(LANDING_ATTEMPT_FILE)
-    if not os.path.lexists(path):
+    path = landing_attempt_path(worktree)
+    if not landing_attempt_exists(path):
         raise LifecycleError("no pre-existing unfinished landing attempt to abandon")
     try:
-        if path.is_symlink() or not path.is_file():
-            raise LifecycleError("landing-attempt provenance is not a regular file")
+        require_regular_landing_attempt(path)
         document = json.loads(path.read_text(encoding="utf-8"))
-        contract_version = document["contractVersion"]
-        keys = [
-            "contractVersion", "worktree", "branch", "rootDevice",
-            "rootInode", "baselineDigest", "generatedFiles",
-            "generatedEvidence", "state", "authorizedEvidence",
-            "pushSucceeded",
-        ]
-        if contract_version == 2:
-            keys.append("policyDigest")
         payload = {
             key: document[key]
-            for key in keys
+            for key in landing_attempt_keys(document["contractVersion"])
         }
         digest = document["sha256"]
         metadata = os.lstat(worktree)
@@ -719,12 +774,108 @@ def abandon_unfinished_landing_attempt(
     ):
         raise LifecycleError("landing-attempt provenance is incoherent")
     archive = path.with_name(
-        f"{path.stem}.abandoned-{int(time() * 1_000_000)}.json"
+        f"{LANDING_ATTEMPT_ARCHIVE_STEM}.v{payload['contractVersion']}"
+        f".abandoned-{int(time() * 1_000_000)}.json"
     )
     durable_replace(path, archive, label="archive landing attempt")
     return archive
 
 
+def canonical_recovery_evidence(
+    canonical: WorktreeProfile,
+    worktree: Path,
+) -> tuple[dict[str, Any], ...]:
+    """Revalidate one frozen landing attempt against canonical policy alone.
+
+    Canonical cleanup-policy drift between attempt start and post-merge cleanup
+    strands an already-merged worktree, because the attempt is bound to the
+    policy that nominated it. This route re-derives deletion authority from the
+    merged canonical policy only. It never re-scans the worktree for new
+    candidates, so broader stale candidate evidence cannot enter; every frozen
+    identity must additionally still be named by canonical policy and still
+    match byte-for-byte on disk, so a narrowed canonical policy, a changed file,
+    and any pre-existing state stop the recovery instead of being deleted.
+    """
+    path = landing_attempt_path(worktree)
+    if not landing_attempt_exists(path):
+        raise LifecycleError(
+            "canonical cleanup recovery requires the landing attempt that froze "
+            "this teardown's evidence"
+        )
+    try:
+        require_regular_landing_attempt(path)
+        document = json.loads(path.read_text(encoding="utf-8"))
+        contract_version = document["contractVersion"]
+        payload = {
+            key: document[key]
+            for key in landing_attempt_keys(contract_version)
+        }
+        digest = document["sha256"]
+        metadata = os.lstat(worktree)
+        branch = run(["git", "branch", "--show-current"], cwd=worktree).stdout.strip()
+    except LifecycleError:
+        raise
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as error:
+        raise LifecycleError(f"landing-attempt provenance is incoherent: {error}") from error
+    if (
+        contract_version != LANDING_ATTEMPT_CONTRACT_VERSION
+        or payload["worktree"] != str(worktree.resolve())
+        or payload["branch"] != branch
+        or not stat.S_ISDIR(metadata.st_mode)
+        or (payload["rootDevice"], payload["rootInode"])
+        != (metadata.st_dev, metadata.st_ino)
+        or not isinstance(payload["generatedFiles"], list)
+        or not isinstance(payload["authorizedEvidence"], list)
+        or type(payload["pushSucceeded"]) is not bool
+        or digest != _baseline_digest(payload)
+    ):
+        raise LifecycleError("landing-attempt provenance is incoherent")
+    if payload["state"] != "frozen" or not payload["pushSucceeded"]:
+        raise LifecycleError(
+            "canonical cleanup recovery requires a frozen landing attempt from a "
+            f"completed push; archive an unfinished attempt with `{ABANDON_ATTEMPT_FLAG}`"
+        )
+    if payload["generatedFiles"]:
+        raise LifecycleError(
+            "landing-start generated paths are consumer-owned and protected: "
+            + ", ".join(payload["generatedFiles"])
+        )
+    baseline = load_artifact_baseline(worktree)
+    if payload["baselineDigest"] != baseline.digest:
+        raise LifecycleError("artifact provenance baseline changed during landing")
+    frozen = tuple(payload["authorizedEvidence"])
+    relatives: list[str] = []
+    for item in frozen:
+        relative = item.get("path") if isinstance(item, dict) else None
+        if not isinstance(relative, str) or relative in relatives:
+            raise LifecycleError("scratch evidence is incoherent")
+        relatives.append(relative)
+    outside = sorted(
+        relative for relative in relatives
+        if not any(
+            path_glob_matches(relative, pattern)
+            for pattern in canonical.landing_generated_artifact_patterns
+        )
+    )
+    if outside:
+        raise LifecycleError(
+            "landing-attempt evidence is outside canonical cleanup policy: "
+            + ", ".join(outside)
+        )
+    with verified_worktree_root(
+        worktree,
+        baseline.root_device,
+        baseline.root_inode,
+    ) as descriptor:
+        current = tuple(
+            contained_regular_identity(descriptor, relative)
+            for relative in relatives
+        )
+    if current != frozen:
+        raise LifecycleError("landing-generated evidence changed after it was frozen")
+    return current
+
+
 def collect_facts(cwd: Path) -> RepoFacts:
     root = Path(run(["git", "rev-parse", "--show-toplevel"], cwd=cwd).stdout.strip()).resolve()
     main = main_worktree(root)