@ikon85/agent-workflow-kit 0.38.0 → 0.40.0

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

@@ -82,12 +82,34 @@ The exact kit-owned commands are:
 Preserve unrelated settings, hook groups, profile sections, and unknown keys.
 Repeated reconciliation with the same choice is byte-identical.
 
+## Planning-artifact ignore rules (offered, never installed)
+
+The planning artefacts the shipped skills write live in the worktree, but
+`.gitignore` is a consumer file the kit does not own: `init` and `update` never
+touch it. Setup may therefore only **offer** the rules, from Section A11, using
+`python3 scripts/worktree-lifecycle/ignore_seed.py`. The kit-owned declaration
+of which artefacts those are is `scripts/worktree-lifecycle/plan-artifacts.json`.
+
+| State | Setup action |
+|---|---|
+| `append` | Show the exact marker block, then ask. |
+| approve | Run `ignore_seed.py apply` once: it appends that one block, append-only. |
+| decline | Write nothing; a later rerun offers it again. |
+| already ignored | Report `nothing to do`; ask nothing and write nothing. |
+| re-run after approval | Byte-identical no-op; never a second block. |
+| consumer-edited block | `blocked` — report the uncovered artefacts and leave the file untouched. |
+
+The seeder never rewrites, reorders, or removes an existing line, and a tracked
+artefact is reported rather than untracked for the consumer. Only this explicit,
+approved step may write `.gitignore`.
+
 ## Scratch classification and sweep
 
 Reconcile an explicit `scratchPatterns` array when enabling a new profile.
 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.
+adoption or rerun. Core never supplies filename defaults — the offered ignore
+rules above are what give that derivation something real to read.
 
 Also reconcile an explicit
 `wrapup.landingGeneratedArtifactPatterns` array. Derive candidates from the
@@ -99,11 +121,40 @@ 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.
+## Profile glob dialect
+
+Every consumer-profile glob in this kit — Worktree Lifecycle and Workflow
+Advisories alike — is matched by the one shared dialect in
+`scripts/profile_globs.py`. There is no second matcher and no per-capability
+variant:
+
+- `*` matches any run of characters inside one path segment, never `/`.
+- `?` matches exactly one character inside one path segment.
+- `[seq]` and `[!seq]` are per-segment character classes; `/` is always a
+  separator and never a class member.
+- `**` as a complete 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.
+- A pattern must match the whole repository-relative path.
+
 Thus `**/__pycache__/**` covers root and nested caches, while `dist-kit/*` does
 not cover `dist-kit/a/b`.
 
+When adopting an existing profile, or after any kit update, review it before
+trusting its patterns:
+
+```bash
+python3 scripts/profile_globs.py docs/agents/workflow-capabilities.json
+```
+
+The check names every pattern whose match set narrows or widens against that
+key's legacy matcher, prints the concrete witness path that proves the
+difference, and marks the keys that carry deletion authority. Exit code 1 means
+at least one pattern needs review. Report the named patterns and let the
+consumer rewrite them; never migrate a pattern automatically and never treat a
+widened deletion-authority pattern as an accepted default. The check reads the
+profile and never edits it.
+
 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

@@ -127,6 +127,30 @@ 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.
 
+An attempt journaled under the superseded v1 contract is **legacy, not
+corruption**. The STOP says so explicitly and names the same
+`--abandon-unfinished-attempt` archive route; archival stays valid for a v1 and
+a v2 receipt even without a creation baseline or a local main profile, and no
+generated or consumer file is deleted or claimed on that route.
+
+If canonical `origin/main` changed its scratch or generator policy *after* the
+attempt started, the PR can merge and cleanup then STOPs with `worktree cleanup
+policy differs from merged canonical origin/main`. That STOP stays fail-closed
+and names its one supported route out:
+
+```bash
+python3 scripts/wrapup-land.py land --branch "<branch>" --recover-canonical-cleanup
+```
+
+This resumes the teardown of an **already-merged** worktree only. It never reads
+the stale worktree candidate policy: it re-reads the merged canonical policy,
+requires the branch to already be an ancestor of canonical `origin/main`, and
+revalidates each frozen landing identity against that canonical policy before
+the ordinary shared assessment and removal run. Evidence the canonical policy no
+longer names, a changed identity, and any pre-existing or foreign file are hard
+STOPs that delete nothing. Re-running after a successful teardown is a no-op.
+The flag is mutually exclusive with `--abandon-unfinished-attempt`.
+
 ### 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

@@ -434,6 +434,12 @@ 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.
 
+You do not have to remember this note. `kit-update` carries a versioned
+registry of required consumer migrations and names any outstanding one in its
+preview and in its terminal report — interactively, under `--yes`, as JSON via
+`update --json`, and in the automated update pull request. It reports the
+decision you still owe; it never writes a cleanup policy for you.
+
 ### 0.33.0 — capability-gated orchestration
 
 `kit-update` reconciles this release for you. These notes matter only if you
@@ -463,6 +469,62 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.40.0 — planning ignore rules are offered, never installed
+
+Nothing in this release requires a consumer action. `kit-update` reconciles it.
+
+Several skills used to state as fact that `PLAN.md`, `PLAN-REVIEW-LOG.md` and
+`ANNAHMEN.md` are gitignored and live on disk only. In your repository that was
+simply untrue: neither `init` nor `update` has ever touched your `.gitignore`,
+and no installed file added those rules — so planning worktrees looked
+permanently dirty, cleanup refused to remove them, and a plan document could be
+committed by accident.
+
+- **The prose is honest now.** The affected skills say the artifacts are
+  *expected* to be ignored and name who can add the rule, instead of asserting
+  an installed guarantee.
+- **`/setup-workflow` offers the rules.** It previews the exact lines, asks
+  first, and appends one idempotent marker block. Declining changes nothing; a
+  re-run is a byte-identical no-op; a block you edited yourself is reported, not
+  repaired; an artifact already tracked by git is reported separately, because
+  an ignore rule cannot untrack it.
+- **`.gitignore` stays yours.** It has no manifest entry, no baseline hash and
+  no three-way reconcile — a file the kit cannot reconcile is one it must not
+  write uninvited. Ordinary `update` reconciliation never reaches the seeder.
+  Decision record:
+  [`docs/adr/0008-planning-ignore-rules-are-offered-never-installed.md`](docs/adr/0008-planning-ignore-rules-are-offered-never-installed.md).
+
+### 0.39.0 — self-explaining guards, one glob dialect, a board you can create
+
+Nothing in this release requires a consumer action. `kit-update` reconciles it.
+
+- **`kit-update` tells you what you still owe.** A versioned registry of
+  required consumer migrations is evaluated against your repository and named in
+  the preview and in the terminal report — interactively, under `--yes`, as JSON
+  via `update --json`, and in the automated update pull request. It reports a
+  decision you owe; it never writes a cleanup policy for you.
+- **`setup-workflow` can create the GitHub-Projects board.** When your tracker
+  is GitHub and no board exists, setup now *offers* to provision one — Status
+  with its stage options plus the workflow fields — and writes the board profile
+  from a read-back of what was actually created. It asks first, and a decline
+  leaves the previous stub path byte-unchanged.
+- **One repository-relative glob dialect.** Worktree Lifecycle and Workflow
+  Advisories now match consumer profile globs through the same matcher, so an
+  advisory and a deletion decision can never disagree about which paths a
+  pattern selects. A review command classifies your installed patterns and
+  reports, with a concrete witness path, any whose match set narrows or widens.
+- **A merged worktree is never stranded.** A landing attempt that started before
+  canonical cleanup policy changed now has a supported recovery route, and a
+  landing journal written by the previous contract version is classified as
+  legacy rather than as corruption — with the exact safe command named in the
+  stop. Both routes revalidate frozen evidence against canonical policy and
+  delete strictly less than the ordinary path.
+- **Guards say what happened and where.** A drift-blocked handoff now names the
+  checkout it evaluated (and says so explicitly when your working directory is a
+  sibling worktree of the same repository), a census status reports *what*
+  drifted rather than only *that* something did, and a handoff anchored on an
+  issue link no longer adopts an issue from a foreign repository.
+
 ### 0.38.0
 
 - added: `docs/adr/0007-session-teardown-requires-provenance-bound-ownership.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.38.0",
+  "kitVersion": "0.40.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -207,7 +207,7 @@
       "ownerSkill": "grill-me",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "e106dbb6f62415cc5eef7d923d864a30e75e108a079d12c0f1624ef7d03d6f6d",
+      "sha256": "b13087563adda186f62aa6206a9233034310ff2458535362246294a45e03079f",
       "mode": 420,
       "origin": "kit"
     },
@@ -247,7 +247,7 @@
       "ownerSkill": "grill-with-docs",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "5616f15e6660270f9f84fba245caa647c47d8af8dc9e526045bb503e7f1f5863",
+      "sha256": "93694d55fe8d164c4c0e0eef27529bd1211acdaddc18224a921c2b0f3b5a10ed",
       "mode": 420,
       "origin": "kit"
     },
@@ -377,7 +377,7 @@
       "ownerSkill": "kit-update",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "ea34bd16072783325c263b4afc4eefc39f0aabdbb53731b84500b46db69ef2c1",
+      "sha256": "15d265be0c2b3b73c32f786644d271fffb4b269cf8e3c624c61296fe838dda9e",
       "mode": 420,
       "origin": "kit"
     },
@@ -447,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
+      "sha256": "fab4fb2f4d6fee820c9b7a737fa955a5ea2cd398987246bd7a04c5fba2c75b26",
       "mode": 420,
       "origin": "kit"
     },
@@ -587,7 +587,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "928a771ecadd4b199169f20deb79647894fe3c0675973b0b97050cad0b675cc4",
+      "sha256": "c6855a479c030f93be30f6fb65b36b8ca317251f9627fd3f6f0f994d9a8b64fb",
       "mode": 420,
       "origin": "kit"
     },
@@ -687,7 +687,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "a5733b71f9257f0999c866bfdea551aedf4b9066572bd484fc263440cb292ca6",
+      "sha256": "29c61411aa42a3f456b3f27fdd15552654b64ef2d72b321bc9c9e11229745626",
       "mode": 420,
       "origin": "kit"
     },
@@ -737,7 +737,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "81ce0f5573d5f062adbc87149172e74ab322315bf348025c0ff2c27f8d8ec67b",
+      "sha256": "6ff4ad3980f0802b3b041e051d86fb4df7a65884c7ded98ff878e2cd584d80f1",
       "mode": 420,
       "origin": "kit"
     },
@@ -757,7 +757,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "e53e6b37bdfdfb0014e2e7ad8fe84cfc2af302eb1a9c6e9e682b1eec05036f1e",
+      "sha256": "f9fb7ef6d4f4e1ed603a5a480d8f97508fd6c99def8194c7ba0a95c62fd3c743",
       "mode": 420,
       "origin": "kit"
     },
@@ -997,7 +997,7 @@
       "ownerSkill": "wrapup",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "2f84b787b81b6f63ebda996a648a6a32c0c79c5894d6471f84250c0f2a24a2c3",
+      "sha256": "de5d451d23b019498104bd8e0ebcbf3385f37aad822496bdb0c47d7021de8761",
       "mode": 420,
       "origin": "kit"
     },
@@ -1087,7 +1087,7 @@
       "path": ".claude/hooks/drift-guard.py",
       "kind": "hook",
       "installRole": "consumer",
-      "sha256": "a248eb3697522b8804fd7d68d1fe3e95613a71829464501c8c7fa4c09d229a64",
+      "sha256": "1480bd322d988a546ed589a2420796b38bbf0f52300598a1dd9aa9ddbeb3ea1d",
       "mode": 493,
       "origin": "kit"
     },
@@ -1489,7 +1489,7 @@
       "ownerSkill": "grill-me",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "ec8d9f299db153a0412b7ef1d01832dc6a765f1819713ca45dc64294541cf9d4",
+      "sha256": "a63331339ed4e018d770face4e7cfe483225ce758a4a1302f39a50239e8187e1",
       "mode": 420,
       "origin": "kit"
     },
@@ -1569,7 +1569,7 @@
       "ownerSkill": "grill-with-docs",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "a17521a8d72eb19316c6adb21837e790c9839834ff441abf3ff44d8e1f63809a",
+      "sha256": "0cb1b41fc6bde94d3e71f3377cbb15b9d7a9a4089df66f591fc907dc19b6c1b5",
       "mode": 420,
       "origin": "kit"
     },
@@ -1699,7 +1699,7 @@
       "ownerSkill": "kit-update",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "ea34bd16072783325c263b4afc4eefc39f0aabdbb53731b84500b46db69ef2c1",
+      "sha256": "15d265be0c2b3b73c32f786644d271fffb4b269cf8e3c624c61296fe838dda9e",
       "mode": 420,
       "origin": "kit"
     },
@@ -1769,7 +1769,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
+      "sha256": "fab4fb2f4d6fee820c9b7a737fa955a5ea2cd398987246bd7a04c5fba2c75b26",
       "mode": 420,
       "origin": "kit"
     },
@@ -1929,7 +1929,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "928a771ecadd4b199169f20deb79647894fe3c0675973b0b97050cad0b675cc4",
+      "sha256": "c6855a479c030f93be30f6fb65b36b8ca317251f9627fd3f6f0f994d9a8b64fb",
       "mode": 420,
       "origin": "kit"
     },
@@ -2029,7 +2029,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "a5733b71f9257f0999c866bfdea551aedf4b9066572bd484fc263440cb292ca6",
+      "sha256": "29c61411aa42a3f456b3f27fdd15552654b64ef2d72b321bc9c9e11229745626",
       "mode": 420,
       "origin": "kit"
     },
@@ -2079,7 +2079,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "81ce0f5573d5f062adbc87149172e74ab322315bf348025c0ff2c27f8d8ec67b",
+      "sha256": "6ff4ad3980f0802b3b041e051d86fb4df7a65884c7ded98ff878e2cd584d80f1",
       "mode": 420,
       "origin": "kit"
     },
@@ -2099,7 +2099,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "e53e6b37bdfdfb0014e2e7ad8fe84cfc2af302eb1a9c6e9e682b1eec05036f1e",
+      "sha256": "f9fb7ef6d4f4e1ed603a5a480d8f97508fd6c99def8194c7ba0a95c62fd3c743",
       "mode": 420,
       "origin": "kit"
     },
@@ -2347,7 +2347,7 @@
       "ownerSkill": "wrapup",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "2f84b787b81b6f63ebda996a648a6a32c0c79c5894d6471f84250c0f2a24a2c3",
+      "sha256": "de5d451d23b019498104bd8e0ebcbf3385f37aad822496bdb0c47d7021de8761",
       "mode": 420,
       "origin": "kit"
     },
@@ -2431,6 +2431,14 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/board_bootstrap.py",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "52f4bc89fb078bb9a8735481488bc60d2be438c5c8175555195ac84775e40bfb",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/board_config.py",
       "kind": "script",
@@ -2555,7 +2563,7 @@
       "path": "scripts/kit-update-pr.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "c28bbd5a45583a92eca12758c1d626e04bce820300178b54933340759d1690fd",
+      "sha256": "17084eede8601d7cf7dd9da85f7738d618111797933a362c93627058fbd335d4",
       "mode": 493,
       "origin": "kit"
     },
@@ -2623,6 +2631,14 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "scripts/profile_globs.py",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "dd11f6e2513eb43813242ace8f4ea00e10b0fa33f4e13fd125afa4a654d61eff",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/program_graph_parse.py",
       "kind": "script",
@@ -2771,7 +2787,7 @@
       "path": "scripts/workflow-advisories/core.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "75b8d8b781344c54edf9f83c6976a999c10ceea6904af765c7179161e82d3bd6",
+      "sha256": "fcc13d24944a9b1534529e62cc1437617e394f6fe3402647c17cee4ea96aade5",
       "mode": 420,
       "origin": "kit"
     },
@@ -2795,7 +2811,23 @@
       "path": "scripts/worktree-lifecycle/core.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "a869ecc4646fc3493b883521594c3976e53b9b896d1361c87e1085adea10052c",
+      "sha256": "50c60de1e0238fa1f5cd627f67e57ca4f378275136691411487f36d7fda580dd",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/ignore_seed.py",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "defd667ed94301cffb0f08e0a910873c246be267cb458adf40f5e7b2109ae4d0",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/worktree-lifecycle/plan-artifacts.json",
+      "kind": "doc",
+      "installRole": "consumer",
+      "sha256": "fe7f805ca9c698f9d77bdda4372f6f5a516b1e60c46ae732a94de184cb0ce3b4",
       "mode": 420,
       "origin": "kit"
     },
@@ -2811,7 +2843,7 @@
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "55c62d00f84e5a1e008d059dc1aad2e026f35dab25437e5cb3c53b717d621a06",
+      "sha256": "0dbba4a87d41171f3fce22a4842eecd2a989ea6a5ddf44832d7b2aed9feb4226",
       "mode": 420,
       "origin": "kit"
     },
@@ -2835,7 +2867,7 @@
       "path": "scripts/wrapup-land.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "f92779efab05fb17447abf47b8aec3fab6a501eff8e11735c245e5f615f9e460",
+      "sha256": "476012558bb786070ce47458c6f0734ff110d5d957af72e13b20d49a37a03592",
       "mode": 493,
       "origin": "kit"
     },

package/docs/adr/0008-planning-ignore-rules-are-offered-never-installed.md

@@ -0,0 +1,84 @@
+# Planning ignore rules are offered, never installed
+
+Status: accepted (2026-07-26, #255)
+
+The shipped planning skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and
+`ANNAHMEN.md` into a session worktree, and several of them told the agent those
+files were gitignored and lived on disk only. In a consumer repository that was
+simply untrue: `init` and `update` never touch `.gitignore`, and no installed
+file adds the rules. The consequence mirrors what this repository fixed for
+itself in #254 — every planning worktree reports a permanently dirty tree, the
+shipped Worktree Lifecycle cleanup refuses to remove it, genuinely unlanded work
+becomes indistinguishable from plan scratch, and a consumer who never notices
+can commit a plan doc into their history that the prose implied could not be
+committed.
+
+The constraint is the consumer contract. Consumer-owned files are written once
+and never overwritten by ordinary reconciliation, and `.gitignore` is stronger
+still: the kit does not own it at all and has no manifest entry, no baseline
+hash, and no three-way reconcile for it. A file the kit cannot reconcile is a
+file the kit must not write uninvited.
+
+We decided to close the gap from both ends:
+
+1. **`/setup-workflow` offers the rules as an explicit, previewed, approved
+   step.** Section A11 previews with
+   `python3 scripts/worktree-lifecycle/ignore_seed.py preview`, shows the exact
+   lines verbatim, asks, and only an approval runs `apply`. The write is
+   append-only inside one idempotent marker block. It never rewrites, reorders,
+   or removes an existing line; a re-run is a byte-identical no-op; a decline
+   changes nothing; a repository that already ignores the artefacts reports
+   `nothing to do`; and a marker block the consumer has since edited is
+   `blocked`, never repaired. Nothing in `init` or `update` can reach the
+   seeder.
+2. **Shipped skill prose states the assumption instead of asserting the fact.**
+   A skill now says these artefacts are *expected* to be ignored and names
+   `/setup-workflow` as the thing that can make it true, rather than claiming
+   the kit already did. The claim is pinned by a census lint over both skill
+   trees, so the assertion cannot silently return.
+
+This is the same shape the kit shipped for the GitHub-Projects board in 0.39.0
+(#24): offer, preview, obtain an explicit yes, never write an outward or
+consumer-owned artefact silently.
+
+Which artefacts the offer covers is a kit-owned fact — the kit knows which files
+its own skills write — declared once in
+`scripts/worktree-lifecycle/plan-artifacts.json`. That is deliberately not the
+consumer's `worktreeLifecycle.scratchPatterns`, which is derived *from* the
+consumer's ignored planning artefacts and would otherwise be circular: before
+this decision there was nothing ignored for it to be derived from.
+
+## Considered options
+
+- **Append-only seed at `init`:** rejected. It respects append-only mechanics
+  but still writes a file the kit does not own, uninvited, on first install —
+  the one action the consumer contract exists to prevent.
+- **Readiness capability only:** rejected. Reporting the gap and letting the
+  affected skills degrade honestly leaves the friction in place and fixes
+  nothing for the consumer who wants the promise to hold.
+- **Prose-only fix:** rejected as insufficient on its own. It removes the false
+  claim but leaves every consumer with dirty planning worktrees and a cleanup
+  that refuses to run. It is kept as one half of the decision, not the whole.
+- **Deriving the rules from `worktreeLifecycle.scratchPatterns`:** rejected as
+  circular, and because that array is consumer-owned deletion-adjacent policy
+  that Core never supplies defaults for.
+- **Untracking an already-committed artefact:** rejected. An ignore rule cannot
+  untrack a tracked file, and running `git rm` on consumer history is far past
+  what a setup step may do. The seeder reports the tracked artefact and stops.
+
+## Consequences
+
+- A consumer who runs `/setup-workflow` and approves gets the guarantee the
+  skills describe; a consumer who declines keeps a byte-identical `.gitignore`
+  and loses nothing but the convenience.
+- The never-overwrite contract is untouched: the only write is an append behind
+  an explicit yes, and `update` reconciliation still never touches
+  `.gitignore`.
+- The offer reaches only consumers who run setup again. That is accepted: it is
+  the price of not writing an unowned file, and re-running `/setup-workflow` is
+  already the documented way to pick up a new project-layer capability.
+- After an approval, `scratchPatterns` derivation finally has real ignored
+  planning artefacts to read, so the Worktree Lifecycle scratch classification
+  stops being vacuous in a fresh consumer repository.
+- A consumer who edits or deletes the marker block owns the outcome; the kit
+  reports and stops rather than restoring its own block.

package/package.json

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