@ikon85/agent-workflow-kit 0.37.0 → 0.38.0

package/.agents/skills/orchestrate-wave/SKILL.md

@@ -141,7 +141,7 @@ replace the ~30-second heartbeat; otherwise the standing heartbeat remains requi
    LOCAL annotated tag, so two sessions racing one wave cannot both win. Either
    `acquired: false` or a work signal you did not create means another session
    owns the wave — **STOP**, report the returned `claim.owner` plus the exact
-   branch/worktree, touch nothing. Local coordination state — never push the tag.
+   branch/worktree, touch nothing. After acquisition, begin the claim-bound teardown receipt with `python3 scripts/worktree-lifecycle/session.py begin --anchor <anchor> --owner <claim-owner> --base <wave-HEAD>`; claim and receipt stay local — never push them.
 4. **Wave worktree**: reuse the planning worktree (never re-create; the handoff
    points there). Bring its branch to current `main`:
    `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
@@ -195,8 +195,8 @@ disjoint wave, conflict hub first. Dispatch only `FREI` slices: re-read
 `frontier <anchor#>` before each wave and clear changed edges only via `dep-remove`.
 Before each slice, bind **(a) inline vs delegate** and **(b) tier + effort** under
 Standing rules. Tiny mechanical work may stay inline.
-For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
-`git worktree add <path> -b feat/<anchor>-<slug>`.
+For Path A/B, create each new worktree through the active receipt: `python3 scripts/worktree-lifecycle/session.py create --anchor <anchor> --owner <claim-owner> --base <wave-HEAD> --profile <profile> <slice-issue> <slug> <type>`.
+It refuses reused/pre-existing targets; never replace this ownership proof with raw `git worktree add`.
 - **Claim each slice issue at builder launch — the wave claim is not a slice
   claim.** It guards the anchor on this machine only; the slice issue is the
   grabbable unit a second machine or cloud agent sees. Before dispatch, skip and
@@ -358,8 +358,8 @@ written · merge order documented.
 - A skill edited during the wave → sync its dual-surface mirror in the SAME PR
   using the tool named by `§Landing` when present; mirror parity remains a pre-PR
   gate.
-- Leave slice worktrees for the user to inspect, or note they're
-  post-merge-removable.
+- After reading every `ANNAHMEN.md`, seal the receipt, inspect it against fetched canonical `main`, then run its `teardown`; only ancestry/one-to-one patch-equivalent exact owned OIDs are compare-deleted, while foreign targets, unique/ambiguous content, changed OIDs, dirty/protected worktrees, and open/unknown PR evidence stop.
+- Keep the completed receipt as recovery-OID evidence; only then release this run's wave claim.
 
 **Done when:** no orphan process · this run's wave claim removed · this run's
 unlanded slice claims released · ANNAHMEN propagated ·

package/.agents/skills/setup-workflow/SKILL.md

@@ -204,11 +204,15 @@ Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
 - **Yes** — create or deepen only the `worktreeLifecycle` section in
   `docs/agents/workflow-capabilities.json`, preserve every other section and
   unknown key, reconcile an explicit consumer-derived `scratchPatterns` array,
+  explicitly derive and review the consumer's
+  `wrapup.landingGeneratedArtifactPatterns` array from real landing outputs,
   and reconcile only the exact kit-owned hook commands listed in the seed.
 - **Later / No** — record the choice in the tracked profile without installing
   hook wiring. Ordinary reruns do not ask again.
 - **Existing** — adopt the current section and wiring without normalizing
-  consumer-owned values.
+  consumer-owned values. Preserve an existing landing-artifact policy
+  byte-for-byte; if it is missing, surface the explicit derivation decision and
+  do not write a default.
 - **Disable** — remove only the exact kit-owned hook commands first, then set
   `enabled: false`; retain the profile, setup policy, and unknown keys.
 
@@ -520,6 +524,9 @@ unknown consumer keys share this profile. Apply the transition and hook
 ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md),
 [workflow-advisories.md](./workflow-advisories.md), and
 [safety-guardrails.md](./safety-guardrails.md) transactionally.
+The landing-artifact policy is deletion authority: it is always an explicit
+consumer-reviewed setup value, never an update-time default or an inference
+from ignored paths.
 
 For Memory Lifecycle, use only the deterministic setup helper from Section A5.
 Do not copy templates with shell commands or edit the capability profile by

package/.agents/skills/setup-workflow/worktree-lifecycle.md

@@ -29,6 +29,7 @@ advisory, and safe cleanup policy as one unit.
     "operations": [
       "record-choice",
       "reconcile-profile-enabled",
+      "reconcile-landing-artifact-policy",
       "reconcile-hook-wiring"
     ]
   },
@@ -50,7 +51,8 @@ advisory, and safe cleanup policy as one unit.
     "state": "existing",
     "choice": "yes",
     "operations": [
-      "adopt-existing"
+      "adopt-existing",
+      "reconcile-landing-artifact-policy"
     ]
   },
   {
@@ -87,6 +89,21 @@ Derive its glob values from the consumer's ignored planning artefacts; an empty
 array is valid. Existing values are consumer-owned and remain byte-identical on
 adoption or rerun. Core never supplies filename defaults.
 
+Also reconcile an explicit
+`wrapup.landingGeneratedArtifactPatterns` array. Derive candidates from the
+consumer's real landing commands and ignored outputs, show the exact list for
+review, and write it only as part of that explicit setup decision. Never copy
+another repository's values or infer deletion authority from `.gitignore`
+alone. An empty array is valid. Existing configured values remain byte-identical.
+If an existing enabled profile lacks the key, report one actionable setup
+decision and leave the project layer unchanged until the consumer confirms the
+derived list.
+
+Patterns use repository-relative POSIX semantics: `*` stays within one segment,
+while `**` crosses `/`; a leading `**/` also matches the repository root.
+Thus `**/__pycache__/**` covers root and nested caches, while `dist-kit/*` does
+not cover `dist-kit/a/b`.
+
 The shipped read-only inventory is
 `python3 scripts/worktree-lifecycle/cleanup.py sweep`. The same profile powers
 its branch issue extraction and scratch-only cleanup verdicts.

package/.agents/skills/wrapup/SKILL.md

@@ -105,6 +105,28 @@ One call covers: push → PR create/reuse (+ drift markers merged into the body)
 
 STOP → diagnose in the main conversation, fix, re-run `land` (an already-merged PR resumes at teardown).
 
+Before merge, the committed worktree policy only nominates exact landing
+evidence. After merge, cleanup reloads `docs/agents/workflow-capabilities.json`
+from canonical `origin/main`; only the identical merged, attempt-bound scratch
+and generator policy authorizes each evidence path and deletion. A mismatch is
+a hard STOP that preserves every file—never bypass it with the unmerged branch
+profile.
+
+Landing provenance has one explicit relinquish route. If the STOP names an
+unfinished or drifted landing attempt and the ambiguous files cannot be restored
+to their frozen identities, run:
+
+```bash
+python3 scripts/wrapup-land.py land --branch "<branch>" --abandon-unfinished-attempt
+```
+
+This archives the started or frozen attempt receipt only. It deletes and claims
+no files, works even when the older creation baseline is missing, and returns
+before push, PR, or merge. The next `land` conservatively protects every current
+matching path; classify or move those blockers first. Do not use relinquish for
+an exact unchanged frozen attempt: a normal retry validates that evidence and
+resumes deterministically.
+
 ### 6 · Post-merge (agent)
 - **Sibling propagation:** for each `drift_markers` entry in the land report, append the note to the target issue's `vor_bau` section + re-stamp its `plan_revision`. Log-based markers → **write directly, then show what was written where** (mandatory report — visibility moved from a pre-gate into the report, decision 2026-07-06); fallback candidates the user hasn't confirmed yet → confirm first. Program context widens the target set to unbuilt wave-stubs/leaves and the Program-PRD itself — same append-only mechanism. **Exception:** appends to the Program-PRD or unbuilt wave-stubs do **not** re-stamp `plan_revision` — that stays reserved for structural wave-plan edits via the `to-waves` escalation path; a mere drift note must not stale-block published stubs.
 - **Anchor close:** report says `anchor_complete: true` → `gh issue close <anchor> -c "Wave complete — all slices merged via PR #<pr>."` and verify board status Done. The guard keeps anchors away from every auto-close — this verified close is the only close path; without it the anchor stays silently open after the last slice. **Then re-run the upward propagation**: the land-time `program-sync` ran BEFORE this close, so on a wave-completing slice the Wellenplan still shows 🔄 and the Phasen-Gate stays unchecked — after the board shows Done, run `python3 scripts/board-sync.py program-sync <program-prd#>` once more (the report's `program_sync.program` names it; skip when the report says the parent is not a program). Board auto-rules can lag the close (Close→Done race) — verify Done first, that's what the token reads.

package/.claude/skills/orchestrate-wave/SKILL.md

@@ -141,7 +141,7 @@ replace the ~30-second heartbeat; otherwise the standing heartbeat remains requi
    LOCAL annotated tag, so two sessions racing one wave cannot both win. Either
    `acquired: false` or a work signal you did not create means another session
    owns the wave — **STOP**, report the returned `claim.owner` plus the exact
-   branch/worktree, touch nothing. Local coordination state — never push the tag.
+   branch/worktree, touch nothing. After acquisition, begin the claim-bound teardown receipt with `python3 scripts/worktree-lifecycle/session.py begin --anchor <anchor> --owner <claim-owner> --base <wave-HEAD>`; claim and receipt stay local — never push them.
 4. **Wave worktree**: reuse the planning worktree (never re-create; the handoff
    points there). Bring its branch to current `main`:
    `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
@@ -195,8 +195,8 @@ disjoint wave, conflict hub first. Dispatch only `FREI` slices: re-read
 `frontier <anchor#>` before each wave and clear changed edges only via `dep-remove`.
 Before each slice, bind **(a) inline vs delegate** and **(b) tier + effort** under
 Standing rules. Tiny mechanical work may stay inline.
-For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
-`git worktree add <path> -b feat/<anchor>-<slug>`.
+For Path A/B, create each new worktree through the active receipt: `python3 scripts/worktree-lifecycle/session.py create --anchor <anchor> --owner <claim-owner> --base <wave-HEAD> --profile <profile> <slice-issue> <slug> <type>`.
+It refuses reused/pre-existing targets; never replace this ownership proof with raw `git worktree add`.
 - **Claim each slice issue at builder launch — the wave claim is not a slice
   claim.** It guards the anchor on this machine only; the slice issue is the
   grabbable unit a second machine or cloud agent sees. Before dispatch, skip and
@@ -358,8 +358,8 @@ written · merge order documented.
 - A skill edited during the wave → sync its dual-surface mirror in the SAME PR
   using the tool named by `§Landing` when present; mirror parity remains a pre-PR
   gate.
-- Leave slice worktrees for the user to inspect, or note they're
-  post-merge-removable.
+- After reading every `ANNAHMEN.md`, seal the receipt, inspect it against fetched canonical `main`, then run its `teardown`; only ancestry/one-to-one patch-equivalent exact owned OIDs are compare-deleted, while foreign targets, unique/ambiguous content, changed OIDs, dirty/protected worktrees, and open/unknown PR evidence stop.
+- Keep the completed receipt as recovery-OID evidence; only then release this run's wave claim.
 
 **Done when:** no orphan process · this run's wave claim removed · this run's
 unlanded slice claims released · ANNAHMEN propagated ·

package/.claude/skills/setup-workflow/SKILL.md

@@ -204,11 +204,15 @@ Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
 - **Yes** — create or deepen only the `worktreeLifecycle` section in
   `docs/agents/workflow-capabilities.json`, preserve every other section and
   unknown key, reconcile an explicit consumer-derived `scratchPatterns` array,
+  explicitly derive and review the consumer's
+  `wrapup.landingGeneratedArtifactPatterns` array from real landing outputs,
   and reconcile only the exact kit-owned hook commands listed in the seed.
 - **Later / No** — record the choice in the tracked profile without installing
   hook wiring. Ordinary reruns do not ask again.
 - **Existing** — adopt the current section and wiring without normalizing
-  consumer-owned values.
+  consumer-owned values. Preserve an existing landing-artifact policy
+  byte-for-byte; if it is missing, surface the explicit derivation decision and
+  do not write a default.
 - **Disable** — remove only the exact kit-owned hook commands first, then set
   `enabled: false`; retain the profile, setup policy, and unknown keys.
 
@@ -520,6 +524,9 @@ unknown consumer keys share this profile. Apply the transition and hook
 ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md),
 [workflow-advisories.md](./workflow-advisories.md), and
 [safety-guardrails.md](./safety-guardrails.md) transactionally.
+The landing-artifact policy is deletion authority: it is always an explicit
+consumer-reviewed setup value, never an update-time default or an inference
+from ignored paths.
 
 For Memory Lifecycle, use only the deterministic setup helper from Section A5.
 Do not copy templates with shell commands or edit the capability profile by

package/.claude/skills/setup-workflow/worktree-lifecycle.md

@@ -29,6 +29,7 @@ advisory, and safe cleanup policy as one unit.
     "operations": [
       "record-choice",
       "reconcile-profile-enabled",
+      "reconcile-landing-artifact-policy",
       "reconcile-hook-wiring"
     ]
   },
@@ -50,7 +51,8 @@ advisory, and safe cleanup policy as one unit.
     "state": "existing",
     "choice": "yes",
     "operations": [
-      "adopt-existing"
+      "adopt-existing",
+      "reconcile-landing-artifact-policy"
     ]
   },
   {
@@ -87,6 +89,21 @@ Derive its glob values from the consumer's ignored planning artefacts; an empty
 array is valid. Existing values are consumer-owned and remain byte-identical on
 adoption or rerun. Core never supplies filename defaults.
 
+Also reconcile an explicit
+`wrapup.landingGeneratedArtifactPatterns` array. Derive candidates from the
+consumer's real landing commands and ignored outputs, show the exact list for
+review, and write it only as part of that explicit setup decision. Never copy
+another repository's values or infer deletion authority from `.gitignore`
+alone. An empty array is valid. Existing configured values remain byte-identical.
+If an existing enabled profile lacks the key, report one actionable setup
+decision and leave the project layer unchanged until the consumer confirms the
+derived list.
+
+Patterns use repository-relative POSIX semantics: `*` stays within one segment,
+while `**` crosses `/`; a leading `**/` also matches the repository root.
+Thus `**/__pycache__/**` covers root and nested caches, while `dist-kit/*` does
+not cover `dist-kit/a/b`.
+
 The shipped read-only inventory is
 `python3 scripts/worktree-lifecycle/cleanup.py sweep`. The same profile powers
 its branch issue extraction and scratch-only cleanup verdicts.

package/.claude/skills/wrapup/SKILL.md

@@ -105,6 +105,28 @@ One call covers: push → PR create/reuse (+ drift markers merged into the body)
 
 STOP → diagnose in the main conversation, fix, re-run `land` (an already-merged PR resumes at teardown).
 
+Before merge, the committed worktree policy only nominates exact landing
+evidence. After merge, cleanup reloads `docs/agents/workflow-capabilities.json`
+from canonical `origin/main`; only the identical merged, attempt-bound scratch
+and generator policy authorizes each evidence path and deletion. A mismatch is
+a hard STOP that preserves every file—never bypass it with the unmerged branch
+profile.
+
+Landing provenance has one explicit relinquish route. If the STOP names an
+unfinished or drifted landing attempt and the ambiguous files cannot be restored
+to their frozen identities, run:
+
+```bash
+python3 scripts/wrapup-land.py land --branch "<branch>" --abandon-unfinished-attempt
+```
+
+This archives the started or frozen attempt receipt only. It deletes and claims
+no files, works even when the older creation baseline is missing, and returns
+before push, PR, or merge. The next `land` conservatively protects every current
+matching path; classify or move those blockers first. Do not use relinquish for
+an exact unchanged frozen attempt: a normal retry validates that evidence and
+resumes deterministically.
+
 ### 6 · Post-merge (agent)
 - **Sibling propagation:** for each `drift_markers` entry in the land report, append the note to the target issue's `vor_bau` section + re-stamp its `plan_revision`. Log-based markers → **write directly, then show what was written where** (mandatory report — visibility moved from a pre-gate into the report, decision 2026-07-06); fallback candidates the user hasn't confirmed yet → confirm first. Program context widens the target set to unbuilt wave-stubs/leaves and the Program-PRD itself — same append-only mechanism. **Exception:** appends to the Program-PRD or unbuilt wave-stubs do **not** re-stamp `plan_revision` — that stays reserved for structural wave-plan edits via the `to-waves` escalation path; a mere drift note must not stale-block published stubs.
 - **Anchor close:** report says `anchor_complete: true` → `gh issue close <anchor> -c "Wave complete — all slices merged via PR #<pr>."` and verify board status Done. The guard keeps anchors away from every auto-close — this verified close is the only close path; without it the anchor stays silently open after the last slice. **Then re-run the upward propagation**: the land-time `program-sync` ran BEFORE this close, so on a wave-completing slice the Wellenplan still shows 🔄 and the Phasen-Gate stays unchecked — after the board shows Done, run `python3 scripts/board-sync.py program-sync <program-prd#>` once more (the report's `program_sync.program` names it; skip when the report says the parent is not a program). Board auto-rules can lag the close (Close→Done race) — verify Done first, that's what the token reads.

package/README.md

@@ -425,6 +425,15 @@ Explicit fork with its own identity and update line instead.
 
 ## Upgrade notes
 
+### 0.38.0 — explicit landing-artifact policy
+
+Existing consumers must run `setup-workflow` once after `kit-update`, review
+the generated `wrapup.landingGeneratedArtifactPatterns` decision in
+`docs/agents/workflow-capabilities.json`, and commit that profile change.
+Until the explicit policy is committed, `wrapup-land` fails closed before
+landing instead of assuming that no generated artifact is eligible for
+session-owned cleanup.
+
 ### 0.33.0 — capability-gated orchestration
 
 `kit-update` reconciles this release for you. These notes matter only if you
@@ -454,6 +463,33 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.38.0
+
+- added: `docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md`
+- added: `scripts/worktree-lifecycle/session.py`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.agents/skills/setup-workflow/worktree-lifecycle.md`
+- changed: `.agents/skills/wrapup/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/worktree-lifecycle.md`
+- changed: `.claude/skills/wrapup/SKILL.md`
+- changed: `README.md`
+- changed: `agent-workflow-kit.package.json`
+- changed: `docs/agents/workflow-capabilities.json`
+- changed: `package.json`
+- changed: `scripts/test_orchestrate_wave_contract.py`
+- changed: `scripts/test_worktree_wrapup_contract.py`
+- changed: `scripts/worktree-lifecycle/README.md`
+- changed: `scripts/worktree-lifecycle/capabilities.json`
+- changed: `scripts/worktree-lifecycle/cleanup.py`
+- changed: `scripts/worktree-lifecycle/core.py`
+- changed: `scripts/worktree-lifecycle/profile.py`
+- changed: `scripts/worktree-lifecycle/setup.py`
+- changed: `scripts/wrapup-land.py`
+- changed: `src/lib/bundle.mjs`
+
 ### 0.37.0
 
 - added: `scripts/test_anchor_table.py`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.37.0",
+  "kitVersion": "0.38.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -447,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "b64529b6449a99a013a97be21826a3ced210ec03458dfd980d3a5e0c257e5238",
+      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
       "mode": 420,
       "origin": "kit"
     },
@@ -687,7 +687,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "6021b95b7ef2f070b7968d3d5c87f72749b0418f22441f0c7b6e2a339c859664",
+      "sha256": "a5733b71f9257f0999c866bfdea551aedf4b9066572bd484fc263440cb292ca6",
       "mode": 420,
       "origin": "kit"
     },
@@ -757,7 +757,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "a124d7a9f96471ac93202c8fa78b76f98f8396a12a786b921ed704320eb63c4e",
+      "sha256": "e53e6b37bdfdfb0014e2e7ad8fe84cfc2af302eb1a9c6e9e682b1eec05036f1e",
       "mode": 420,
       "origin": "kit"
     },
@@ -997,7 +997,7 @@
       "ownerSkill": "wrapup",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "7e50b98441747d370b1feefae6ee5e63b859d2243b64f72024534a71b1d64482",
+      "sha256": "2f84b787b81b6f63ebda996a648a6a32c0c79c5894d6471f84250c0f2a24a2c3",
       "mode": 420,
       "origin": "kit"
     },
@@ -1769,7 +1769,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "b64529b6449a99a013a97be21826a3ced210ec03458dfd980d3a5e0c257e5238",
+      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
       "mode": 420,
       "origin": "kit"
     },
@@ -2029,7 +2029,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "6021b95b7ef2f070b7968d3d5c87f72749b0418f22441f0c7b6e2a339c859664",
+      "sha256": "a5733b71f9257f0999c866bfdea551aedf4b9066572bd484fc263440cb292ca6",
       "mode": 420,
       "origin": "kit"
     },
@@ -2099,7 +2099,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "a124d7a9f96471ac93202c8fa78b76f98f8396a12a786b921ed704320eb63c4e",
+      "sha256": "e53e6b37bdfdfb0014e2e7ad8fe84cfc2af302eb1a9c6e9e682b1eec05036f1e",
       "mode": 420,
       "origin": "kit"
     },
@@ -2347,7 +2347,7 @@
       "ownerSkill": "wrapup",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "7e50b98441747d370b1feefae6ee5e63b859d2243b64f72024534a71b1d64482",
+      "sha256": "2f84b787b81b6f63ebda996a648a6a32c0c79c5894d6471f84250c0f2a24a2c3",
       "mode": 420,
       "origin": "kit"
     },
@@ -2779,7 +2779,7 @@
       "path": "scripts/worktree-lifecycle/capabilities.json",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "e80501bd86bbdb0ba296fc6b172442d8ad128f43e571777698657491279e4305",
+      "sha256": "689910f11b51a5f2938989a82378332375e614f2684fe4cc48db7a4ce5c12f4b",
       "mode": 420,
       "origin": "kit"
     },
@@ -2787,7 +2787,7 @@
       "path": "scripts/worktree-lifecycle/cleanup.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "3c1c1113298c7c81b26850df95db8571574a49610cea25b57e208e2fa0a40af9",
+      "sha256": "4671aa6d40590abe103509916abda34e1717b43f7f0f521fc7fe90e1e29be50d",
       "mode": 493,
       "origin": "kit"
     },
@@ -2795,7 +2795,7 @@
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "d4846481f0e7eaeb8e87324a705f94ca323163e3d368b2d809bb572dfea6cd9b",
+      "sha256": "a869ecc4646fc3493b883521594c3976e53b9b896d1361c87e1085adea10052c",
       "mode": 420,
       "origin": "kit"
     },
@@ -2803,7 +2803,7 @@
       "path": "scripts/worktree-lifecycle/profile.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "ad98f18aa6a24a08fdcbf271c0a7f14543ebb1a085ff3343966ce18f115781a5",
+      "sha256": "4a76462e4a9f7c4c3fd1b199217f8c68b9946c49bc934eef7bc888244bdbd16f",
       "mode": 420,
       "origin": "kit"
     },
@@ -2811,15 +2811,23 @@
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "567a59845db059fc6385ea200a8f361e1250f857babaef01d9fa15054be0f753",
+      "sha256": "55c62d00f84e5a1e008d059dc1aad2e026f35dab25437e5cb3c53b717d621a06",
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/worktree-lifecycle/session.py",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "18c2794aaf9fef96a15000c515b600345d3bf1715e23b07d0646156e601ea35a",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/worktree-lifecycle/setup.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "0021c50809373335e9dafe97196f42ad039152418baa49e2004b25ba33d137e2",
+      "sha256": "fa84d0056b24263389e0d17746abc8dc0afbd0152c323a62a6d7590ca9c62cac",
       "mode": 493,
       "origin": "kit"
     },
@@ -2827,7 +2835,7 @@
       "path": "scripts/wrapup-land.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "0f365204c5fd1b707a19fda0c4b4c4c9395f371adeaa8aa808f47e8d94a54bf6",
+      "sha256": "f92779efab05fb17447abf47b8aec3fab6a501eff8e11735c245e5f615f9e460",
       "mode": 493,
       "origin": "kit"
     },

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

@@ -0,0 +1,88 @@
+# Session teardown requires provenance-bound ownership
+
+Status: accepted (2026-07-26, Wave #271)
+
+Long agent sessions create branches, linked worktrees, setup outputs, and
+landing-time build artifacts. The desired end state is that every
+provenance-captured target created by that session can be removed, including
+branches whose changes reached
+canonical `main` through patch-equivalent commits rather than ancestry.
+
+Repository state alone cannot identify that ownership safely. A foreign branch
+can have the same name or patch, a user file can match a generated-artifact
+pattern, and a path can be replaced between assessment and deletion. Retrying
+after a crash adds a time dimension: a fresh snapshot cannot distinguish an
+earlier generator output from a file created by the user between attempts.
+
+We decided that teardown authority must come from **Teardown provenance**, not
+from present-day similarity:
+
+1. A session records intent before creation, but receives cleanup authority only
+   through an atomic **Ownership proof**. Branch and proof ref are acquired in
+   one Git transaction bound to the active wave claim.
+2. Setup, session work, and landing are separate provenance boundaries. Setup
+   and session cleanup use the worktree-creation baseline; landing cleanup uses
+   a persisted landing-attempt boundary and freezes the exact outputs of its
+   generator-capable step.
+3. Paths and patterns select candidates but never prove identity. Cleanup binds
+   regular files and worktree roots to no-follow object evidence and revalidates
+   that evidence immediately before mutation.
+4. The **Lifecycle receipt** is a durably replaced state-transition journal.
+   Prepared Git ref transactions close the worktree-removal race, and committed
+   intermediate states make known outcomes resumable. An external SIGKILL may
+   still leave Git's own lock files requiring operator recovery.
+5. Lost evidence is not reconstructed from coincidence. An interrupted landing
+   attempt without frozen outputs can be archived without claiming or deleting
+   its files, after which the ambiguous files must be classified before a new
+   attempt proceeds.
+
+## Considered options
+
+- **Delete branches merged by ancestry:** rejected because squash,
+  cherry-pick, and patch-equivalent integration leave session-owned branch refs
+  outside ancestry.
+- **Treat a receipt row as ownership:** rejected because another process can
+  create the named branch or worktree after the absence check but before the
+  attempted creation.
+- **Authorize files by ignored path or generator pattern:** rejected because a
+  consumer file can occupy the same path before landing or replace an assessed
+  output afterward.
+- **Take a fresh landing snapshot on every retry:** rejected because it protects
+  prior generator outputs as if they predated landing, while a persistent start
+  snapshot alone incorrectly claims every later matching user file.
+- **Force-remove apparently clean targets:** rejected because force bypasses the
+  repository and filesystem evidence that distinguishes owned work from foreign
+  work.
+- **Guess ownership after an unjournaled crash window:** rejected because safe
+  cleanup and guaranteed automatic liveness cannot both be recovered after the
+  distinguishing evidence is lost.
+
+## Consequences
+
+- A completed session can remove its exact worktrees, branches, proof refs, and
+  provenance-captured generated artifacts without hiding history or sweeping
+  unrelated repository state.
+- Foreign branches, worktrees, replacement symlinks, replacements, late writes,
+  and pre-landing consumer files are hard stops or remain outside cleanup
+  authority. Setup recovery may remove only a symlink whose exact no-follow
+  identity it captured as setup-created.
+- Exact unchanged frozen evidence is deterministically resumable. Started or
+  drifted frozen attempts can be explicitly relinquished by archiving only the
+  receipt; every current file then remains protected and must be classified
+  before another attempt.
+- Provenance-less legacy worktrees receive only a conservative baseline after
+  exact registration, no-follow root, attached branch, and clean tracked/index
+  checks. Setup reuse defers backfill while tracked work or current
+  landing-generated blockers remain. Landing classifies those blockers before
+  writing evidence; after they are moved, all remaining current ignored and
+  untracked files become protected. Corrupt evidence and active attempts are
+  never backfilled.
+- Before merge, a committed worktree policy may nominate only exact,
+  identity-bound cleanup candidates; it authorizes no deletion. After merge,
+  the profile is reloaded directly from canonical `origin/main` and must match
+  both the candidate and attempt-bound policy digest before any mutation.
+  Generator evidence is also reauthorized path-by-path against that canonical
+  policy. Missing policy, an unmerged widening, or branch/canonical drift
+  preserves every file.
+- The lifecycle implementation is necessarily a small transaction protocol,
+  with more states and race tests than a path-based cleanup script.

package/docs/agents/workflow-capabilities.json

@@ -7,12 +7,22 @@
     "branchRegex": "^(?:feat|fix|chore|docs)/(?P<issue>\\d+)-",
     "mainBranches": ["main"],
     "protectedBranches": ["main"],
-    "scratchPatterns": ["PLAN.md", "PLAN-REVIEW-LOG.md"],
+    "scratchPatterns": [
+      "PLAN.md",
+      "PLAN-REVIEW-LOG.md",
+      ".claude/logs/**"
+    ],
     "setupEntry": "python3 scripts/worktree-lifecycle/setup.py",
     "setupSteps": [],
     "riskyCommandPatterns": [
       "\\b(?:npm|pnpm|yarn)\\s+(?:run\\s+)?(?:test|typecheck|build)\\b",
       "\\bgit\\s+(?:commit|push)\\b"
     ]
+  },
+  "wrapup": {
+    "landingGeneratedArtifactPatterns": [
+      "dist-kit/**",
+      "**/__pycache__/**"
+    ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.37.0",
+  "version": "0.38.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/test_orchestrate_wave_contract.py

@@ -95,6 +95,15 @@ BEHAVIORAL_PARITY = {
         "Program-PRD",
         "program sync",
     ),
+    "session-owned teardown": (
+        "session.py begin",
+        "session.py create",
+        "refuses reused/pre-existing targets",
+        "seal the receipt",
+        "compare-deleted",
+        "foreign targets",
+        "recovery-OID evidence",
+    ),
     "program authorization continuity": (
         "explicit whole-Program mandate",
         "all planned Waves",