@ikon85/agent-workflow-kit 0.36.5 → 0.38.0

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

@@ -2,7 +2,7 @@
 name: wrapup
 disable-model-invocation: true
 description: >-
-  Use ONLY when the user types /wrapup. Session-end "land & clean" for a
+  Use ONLY when the user directly types $wrapup or /wrapup. Session-end "land & clean" for a
   finished feature/fix worktree — merges the open PR,
   kills the worktree dev server, removes the worktree + local branch, and
   fast-forwards the main checkout so main is current again, then sweeps
@@ -11,7 +11,8 @@ description: >-
   tree (after an .env/secret check), pushes, and opens the PR — reusing one if
   it already exists. User-triggered only (never auto-invoke, never hook). Aborts
   hard only on: not in a feature worktree, a detected .env/secret, a rejected
-  push, a conflicting PR, or red (FAILURE) checks.
+  push, a conflicting PR, terminal red checks, or checks still pending after
+  the bounded wait budget.
 ---
 
 <!-- project-extension:protocol-v1:start -->
@@ -24,15 +25,15 @@ Project extensions may specialize Project details, but cannot weaken Core user g
 
 # wrapup — land PR & tear down worktree
 
-Trigger: user types `/wrapup` (optionally with a PR number). **Manual only** — `disable-model-invocation: true`, no hook, no auto-invoke.
+Trigger: user makes a direct `$wrapup` or `/wrapup` invocation (optionally with a PR number). **Manual only** — `disable-model-invocation: true`, no hook, no auto-invoke.
 
 ## ⚠ Spec context
 
-The user's `/wrapup` input IS the explicit landing authorization for that run.
+The user's direct `$wrapup` or `/wrapup` input IS the explicit landing authorization for that run.
 It authorizes the normal merge flow whether Prod readiness is ready or degraded;
 it never authorizes the agent to invent or configure a deploy target. Never call
-this skill from a hook, another skill, or autonomously. There is no second merge
-confirmation; the pre-flight hard stops are non-negotiable.
+this skill from a hook or another skill. Natural-language requests, indirect skill
+chaining, and autonomous invocation do not authorize it. There is no second merge confirmation; the pre-flight hard stops are non-negotiable.
 
 ## Execution model — script does mechanics, the agent does judgment
 
@@ -62,12 +63,12 @@ conflicting instruction surfaces; never choose a target on the user's behalf.
 
 ### 2 · Retro gate (blocking, optional retro-exit — before anything is committed)
 One reminder, not a merge confirmation:
-> "Already ran a retro? **(a)** yes / continue → landing now. **(b)** you want one first → the retro starts now; afterwards, invoke `/wrapup` again — repo-file patches then travel in this PR."
+> "Already ran a retro? **(a)** yes / continue → landing now. **(b)** you want one first → the retro starts now; afterwards, invoke `$wrapup` or `/wrapup` again — repo-file patches then travel in this PR."
 
 (b) → **invoke the `retro` skill immediately in this run.** Retro is
 model-invocable and non-deploying, and every mutation still has its own approval
 gate. After retro finishes, **land nothing in this run**. Require a **fresh
-explicit `/wrapup` invocation** because retro may have changed the exact diff
+explicit `$wrapup` or `/wrapup` invocation** because retro may have changed the exact diff
 that the next merge authorization covers.
 
 General chaining rule: automatically chain only into a **model-invocable**,
@@ -100,10 +101,32 @@ Run **from the main tree** (the script refuses inside the worktree — an in-wor
 ```bash
 python3 scripts/wrapup-land.py land --branch "<branch>" --title "<title>" --body-file /tmp/wrapup-pr-body.md
 ```
-One call covers: push → PR create/reuse (+ drift markers merged into the body) → `pr-body-check.py` gate (exit 1 = STOP, exit 2 = fail-open warning) → merge gate (red check / `CONFLICTING` = STOP; fresh-PR `UNKNOWN` mergeable passes — the merge itself is the real gate) → **merge** (`--merge` + `--delete-branch`, verified `MERGED`) → dev-server kill (`.dev-ports` ports + cwd-under-worktree walk, own shell ancestry excluded) → worktree remove (no `--force`; refusal = STOP, check surviving processes first) → main `--ff-only` pull + `branch -d` → issue-close verify (auto-close misses are closed manually) → local merged-branch sweep (`-d` only — squash/rebase-merged branches stay a manual call by design) → remote merged-PR sweep (opt-in `wrapup.remoteBranchSweep` in the board profile; PR-status-authoritative via `ls-remote`; deleted remote branches are restorable from the PR page) → anchor-sync (dry-run diff in the report) + anchor completeness check + `execute-ready-check --mode audit` → **upward propagation:** if the anchor's native parent is a Program-PRD, `program-sync` refreshes its Wellenplan (Status + Issue cells) and checks off mechanically completed Phasen-Gates — the slice event is visible at the program level, not only in the wave (`program_sync` block in the report; skipped when the parent isn't a program).
+One call covers: push → PR create/reuse (+ drift markers merged into the body) → `pr-body-check.py` gate (exit 1 = STOP, exit 2 = fail-open warning) → merge gate (pending/null-conclusion checks poll for up to 20 minutes with progress on stderr; terminal red / `CONFLICTING` / timeout = STOP; known zero-step billing or runner failures are named `infrastructure failure`; an already-`MERGED` PR resumes at teardown) → **merge** (`--merge` + `--delete-branch`, verified `MERGED`) → dev-server kill (`.dev-ports` ports + cwd-under-worktree walk, own shell ancestry excluded) → worktree remove (no `--force`; refusal = STOP, check surviving processes first) → main `--ff-only` pull + `branch -d` → issue-close verify (auto-close misses are closed manually) → local merged-branch sweep (`-d` only — squash/rebase-merged branches stay a manual call by design) → remote merged-PR sweep (opt-in `wrapup.remoteBranchSweep` in the board profile; PR-status-authoritative via `ls-remote`; deleted remote branches are restorable from the PR page) → anchor-sync (dry-run diff in the report) + anchor completeness check + `execute-ready-check --mode audit` → **upward propagation:** if the anchor's native parent is a Program-PRD, `program-sync` refreshes its Wellenplan (Status + Issue cells) and checks off mechanically completed Phasen-Gates — the slice event is visible at the program level, not only in the wave (`program_sync` block in the report; skipped when the parent isn't a program).
 
 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.
@@ -118,5 +141,5 @@ STOP → diagnose in the main conversation, fix, re-run `land` (an already-merge
 <!-- readiness:end -->
 
 ## Out of scope
-- Live-verify / DoD: must happen **before** `/wrapup` — this skill lands, it does not verify.
+- Live-verify / DoD: must happen **before** `$wrapup` or `/wrapup` — this skill lands, it does not verify.
 - Other worktrees / their servers stay untouched.

package/README.md

@@ -322,6 +322,7 @@ rolls that migration back with the rest of the candidate.
 ```sh
 npx github:iKon85/agent-workflow-kit diff        # preview an update (dry run, writes nothing)
 npx github:iKon85/agent-workflow-kit update      # apply it
+npx github:iKon85/agent-workflow-kit update --yes --keep-deleted  # headless/CI
 npx github:iKon85/agent-workflow-kit uninstall   # remove kit-installed files
 ```
 
@@ -369,9 +370,17 @@ Containment and file type are revalidated when read.
 Ownership commands are designed for a single-user CLI workflow and are not
 concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 `--force` (overwrite pre-existing untracked files on `init`), `--yes` / `-y`
-(confirm only already-classified safe update actions), and
+(run `update` non-interactively and confirm only already-classified safe
+actions), `--keep-deleted` (follow upstream deletions and remove those files
+locally), `--restore-deleted` (retain files that were deleted upstream), and
 `--as=explicit-fork` for `own`.
 
+A headless `update` requires `--yes`; otherwise it exits before reading release
+state or touching consumer files. The mutually exclusive deletion flags only
+override the blanket answer for files removed upstream. They never resolve an
+ownership collision or content conflict, so a conflicted headless update still
+prints its report, exits non-zero, and leaves the consumer byte-identical.
+
 The optional Contribution Routing capability is consumer-owned:
 
 ```json
@@ -416,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
@@ -445,6 +463,75 @@ 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`
+- added: `scripts/test_wrapup_land.py`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.agents/skills/setup-workflow/orchestrate-wave-seed.md`
+- changed: `.agents/skills/setup-workflow/worktree-lifecycle.md`
+- changed: `.agents/skills/wrapup/SKILL.md`
+- changed: `.claude/hooks/migration-snapshot-reminder.py`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/orchestrate-wave-seed.md`
+- changed: `.claude/skills/setup-workflow/worktree-lifecycle.md`
+- changed: `.claude/skills/skill-manifest.json`
+- changed: `.claude/skills/wrapup/SKILL.md`
+- changed: `README.md`
+- changed: `agent-workflow-kit.package.json`
+- changed: `docs/agents/workflow-capabilities.json`
+- changed: `scripts/anchor_table.py`
+- changed: `scripts/project-skill-extension.mjs`
+- changed: `scripts/readiness.mjs`
+- changed: `scripts/release-state.mjs`
+- changed: `scripts/release-state.test.mjs`
+- changed: `scripts/test_board_sync_create_idempotency.py`
+- changed: `scripts/test_board_sync_wave_title.py`
+- changed: `scripts/test_census_backstop.py`
+- changed: `scripts/test_orchestrate_wave_contract.py`
+- changed: `scripts/test_retro_wrapup_contract.py`
+- changed: `scripts/workflow-advisories/core.py`
+- changed: `scripts/worktree-lifecycle/README.md`
+- changed: `scripts/worktree-lifecycle/cleanup.py`
+- changed: `scripts/worktree-lifecycle/core.py`
+- changed: `scripts/worktree-lifecycle/profile.py`
+- changed: `scripts/wrapup-land.py`
+- changed: `src/cli.mjs`
+- changed: `src/lib/manifest.mjs`
+- changed: `src/lib/projectSkillExtension.mjs`
+- changed: `src/lib/updateCandidate.mjs`
+- changed: `src/lib/updateDecisions.mjs`
+- changed: `src/lib/verifyUpdateCandidateProtocol.mjs`
+
 ### 0.36.5
 
 - changed: `src/lib/updateCandidate.mjs`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.36.5",
+  "kitVersion": "0.38.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -447,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "36570dfccd6dcfa41774e56fd8e31c794a31da72a609753291cf29f87d2636d6",
+      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
       "mode": 420,
       "origin": "kit"
     },
@@ -667,7 +667,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "4ced75934cb409903344f196253e99c1166d7c8705d92c477bfeda92f8a9cadf",
+      "sha256": "78f24c6f32bb4b3dd65293c2121b726fbf495f95d884d0527a32b6f1cfae52f5",
       "mode": 420,
       "origin": "kit"
     },
@@ -687,7 +687,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "697ef6f6cdb749bf0646b2add95d4d3246df39c48ca6d9ade063a775690ce462",
+      "sha256": "a5733b71f9257f0999c866bfdea551aedf4b9066572bd484fc263440cb292ca6",
       "mode": 420,
       "origin": "kit"
     },
@@ -757,7 +757,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "5e0914874f0b9f940205fbcfcfbba87d0c2df8f31db104d2c5328a0d20c80616",
+      "sha256": "e53e6b37bdfdfb0014e2e7ad8fe84cfc2af302eb1a9c6e9e682b1eec05036f1e",
       "mode": 420,
       "origin": "kit"
     },
@@ -997,7 +997,7 @@
       "ownerSkill": "wrapup",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "51fcbabb90f3b04c46079ed9fb491592d0dbad1e1069723e6054376415127fa0",
+      "sha256": "2f84b787b81b6f63ebda996a648a6a32c0c79c5894d6471f84250c0f2a24a2c3",
       "mode": 420,
       "origin": "kit"
     },
@@ -1143,7 +1143,7 @@
       "path": ".claude/hooks/migration-snapshot-reminder.py",
       "kind": "hook",
       "installRole": "consumer",
-      "sha256": "693227fae1aa3e782ed5b61a9e8c3fc8c1880a617efd14cb86ca7f38d9a8f204",
+      "sha256": "0cf691143fc4dbac210f45be35e037686adf678f6f521cfd80d9100bcfbb7e02",
       "mode": 493,
       "origin": "kit"
     },
@@ -1769,7 +1769,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "672d251912886ac4e44f2a60fd3a35ee82c44e86bef4c19ae40d506eb1cf1427",
+      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
       "mode": 420,
       "origin": "kit"
     },
@@ -2009,7 +2009,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "4ced75934cb409903344f196253e99c1166d7c8705d92c477bfeda92f8a9cadf",
+      "sha256": "78f24c6f32bb4b3dd65293c2121b726fbf495f95d884d0527a32b6f1cfae52f5",
       "mode": 420,
       "origin": "kit"
     },
@@ -2029,7 +2029,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "697ef6f6cdb749bf0646b2add95d4d3246df39c48ca6d9ade063a775690ce462",
+      "sha256": "a5733b71f9257f0999c866bfdea551aedf4b9066572bd484fc263440cb292ca6",
       "mode": 420,
       "origin": "kit"
     },
@@ -2099,7 +2099,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "5e0914874f0b9f940205fbcfcfbba87d0c2df8f31db104d2c5328a0d20c80616",
+      "sha256": "e53e6b37bdfdfb0014e2e7ad8fe84cfc2af302eb1a9c6e9e682b1eec05036f1e",
       "mode": 420,
       "origin": "kit"
     },
@@ -2107,7 +2107,7 @@
       "path": ".claude/skills/skill-manifest.json",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "290cc3e847a10cb10b4ecb17cf0d45be0f60f95e96b7a70417b3e8da0a32e23c",
+      "sha256": "d2f918149db5d75cc389279afc93516d7c12aca790ddb49de23b198d055c8377",
       "mode": 420,
       "origin": "kit"
     },
@@ -2347,7 +2347,7 @@
       "ownerSkill": "wrapup",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "33b1de1f10d6ca94b89057d8b1f1afe06ae89209991ea3b6d811a8fb61f910b6",
+      "sha256": "2f84b787b81b6f63ebda996a648a6a32c0c79c5894d6471f84250c0f2a24a2c3",
       "mode": 420,
       "origin": "kit"
     },
@@ -2427,7 +2427,7 @@
       "path": "scripts/anchor_table.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "204f2cfce8e641721656e745aa5b9bb664be5fc37667dcd8bc6528b8209aaec3",
+      "sha256": "b8bd0e654137a1e7d309f431ab6e7f76e8049c6a3206730323ae7cc90ebc06e8",
       "mode": 420,
       "origin": "kit"
     },
@@ -2667,7 +2667,7 @@
       "path": "scripts/project-skill-extension.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "12b7c381774a3db6c0d99ec855337a928b70bbe612012bb06f546afb397efc87",
+      "sha256": "9b038bfef135ba2f8487ced43b863631ddbcb3772700a87b6208f0e95b5213e9",
       "mode": 493,
       "origin": "kit"
     },
@@ -2675,7 +2675,7 @@
       "path": "scripts/readiness.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "26514c49316aa29fdeeb74fca0655cd7aa801f37e3c81cbd2551bb158138ebe8",
+      "sha256": "385854b0a1d8f7915c59cc4f35a3ee6774c4d4ac631a96357abe11cb81be3021",
       "mode": 493,
       "origin": "kit"
     },
@@ -2699,7 +2699,7 @@
       "path": "scripts/release-state.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "fd9f7f86e26ab3faba819e0c46e5e87c2dd3a84dc9a6111b4eceb4ebe6a3a344",
+      "sha256": "8e3f640aee36bf83ae4b49e449dd98eac6b747b323909ea947d4829345ccb743",
       "mode": 420,
       "origin": "kit"
     },
@@ -2771,7 +2771,7 @@
       "path": "scripts/workflow-advisories/core.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "dc47bc20ed1107d230f45ff7158e4fd81d6473be515e03cbd52274f3e87d840d",
+      "sha256": "75b8d8b781344c54edf9f83c6976a999c10ceea6904af765c7179161e82d3bd6",
       "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": "370af8840732db3b6ba39b4825686f3980f69f612038123bc86b2c68921f02ca",
+      "sha256": "4671aa6d40590abe103509916abda34e1717b43f7f0f521fc7fe90e1e29be50d",
       "mode": 493,
       "origin": "kit"
     },
@@ -2795,7 +2795,7 @@
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "d54c4d663c234b7d2e607b99f6090b46104c21ba4326ef03bcb65de39d1cce19",
+      "sha256": "a869ecc4646fc3493b883521594c3976e53b9b896d1361c87e1085adea10052c",
       "mode": 420,
       "origin": "kit"
     },
@@ -2803,7 +2803,7 @@
       "path": "scripts/worktree-lifecycle/profile.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "993b105efd2329b3a206b0c79399aff1c7840017362745966f9b158b1f165f09",
+      "sha256": "4a76462e4a9f7c4c3fd1b199217f8c68b9946c49bc934eef7bc888244bdbd16f",
       "mode": 420,
       "origin": "kit"
     },
@@ -2811,15 +2811,23 @@
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "5dba0332253c37162ad1b2f1b7bf504a23af85bf297fdaa8920036f610ff754a",
+      "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": "ee1f567e7be4f7baae222ed3974d39e5efee93edb2a663cacc8e18b567fa837e",
+      "sha256": "f92779efab05fb17447abf47b8aec3fab6a501eff8e11735c245e5f615f9e460",
       "mode": 493,
       "origin": "kit"
     },
@@ -2883,7 +2891,7 @@
       "path": "src/lib/manifest.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "f2920f2b25a700be080fbba122a809bf509080673b806aaab2b0c773c8d8267f",
+      "sha256": "9f8b4cc90d710a616efd82dce2389504efb27781ffa769f9617108dcba96cb0e",
       "mode": 420,
       "origin": "kit"
     },
@@ -2899,7 +2907,7 @@
       "path": "src/lib/projectSkillExtension.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "2d8708b230bd9d34474c613cfffc89bdbd11cc128837cdaeab12fc06acea2b04",
+      "sha256": "63fa51c0aa6a0bf1b7168467c33810ecca95d9f1252a1455cbce122d3d4cf8d2",
       "mode": 420,
       "origin": "kit"
     },
@@ -3091,7 +3099,7 @@
       "path": "src/lib/updateDecisions.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "d80969d5d8c6b084289dfc4871924fb1835bbec6cf08b859ecd81bb95e6f767b",
+      "sha256": "1df6ce6a281fb559b9c7663905f67ab3a4cdae80b365882a395f7b37b57e1672",
       "mode": 420,
       "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,11 +7,22 @@
     "branchRegex": "^(?:feat|fix|chore|docs)/(?P<issue>\\d+)-",
     "mainBranches": ["main"],
     "protectedBranches": ["main"],
+    "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.36.5",
+  "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/anchor_table.py

@@ -29,7 +29,7 @@ SLICE_TABLE_START = "<!-- slice-table:start -->"
 SLICE_TABLE_END = "<!-- slice-table:end -->"
 
 _SUBISSUE_NUM_RE = re.compile(r"#(\d+)")
-_STATUS_BASE_RE = re.compile(r"^(✅\s*#\d+|🔄|⬜)")
+_STATUS_BASE_RE = re.compile(r"^(✅(?:\s*#\d+)?|🔄|⬜)")
 _STATUS_RANK = {"⬜": 0, "🔄": 1}
 
 
@@ -113,17 +113,23 @@ def first_subissue_num(cell: str) -> Optional[int]:
 
 # --- volatile-cell refresh (board → cell) ------------------------------------
 def status_token_from_board(entry: dict, roles: dict) -> str:
-    """Canonical Status token from board state: ✅ #<PR> (merged) · 🔄 (open PR or
-    an in-flight board status) · ⬜ (otherwise).
-
-    Which status NAMES count as in-flight comes from the profile's role map
-    (`roles["inProgress"]`/`roles["review"]`) — passed in as a plain
-    dict so this module stays pure (no board_config import). Empty roles →
-    board-status names can't be interpreted (⬜), PR signals still work."""
+    """Canonical Status token from board state: ✅ #<PR> (merged) · ✅ (closed
+    issue in the configured done status) · 🔄 (open PR or an in-flight board
+    status) · ⬜ (otherwise).
+
+    Status NAMES come from the profile's role map (`roles["done"]`,
+    `roles["inProgress"]`, `roles["review"]`) — passed in as a plain dict so
+    this module stays pure (no board_config import). Empty roles → board-status
+    names can't be interpreted (⬜), PR signals still work."""
     prs = entry.get("prs") or []
     merged = [p for p in prs if p.get("state") == "MERGED"]
     if merged:
         return f"✅ #{merged[-1]['number']}"
+    done = roles.get("done")
+    if (done is not None
+            and entry.get("state") == "closed"
+            and entry.get("status") == done):
+        return "✅"
     active = {roles.get("inProgress"), roles.get("review")} - {None}
     if [p for p in prs if p.get("state") == "OPEN"] or entry.get("status") in active:
         return "🔄"