@ikon85/agent-workflow-kit 0.39.0 → 0.40.0

package/.agents/skills/grill-me/SKILL.md

@@ -52,7 +52,7 @@ For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-sta
 
 ## Plan-lock — writing PLAN.md
 
-Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
+Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root. `PLAN.md` is **expected** to be ignored by git so it never travels over git — the kit never edits your `.gitignore` by itself, but `/setup-workflow` offers to add that rule (consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
 
 ## Re-grill reconcile — execute-ready (Wave 26)
 

package/.agents/skills/grill-with-docs/SKILL.md

@@ -40,7 +40,7 @@ For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-sta
 
 ## Plan-lock — writing PLAN.md
 
-Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
+Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root. `PLAN.md` is **expected** to be ignored by git so it never travels over git — the kit never edits your `.gitignore` by itself, but `/setup-workflow` offers to add that rule (consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
 
 </plan-lock>
 

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

@@ -146,8 +146,8 @@ replace the ~30-second heartbeat; otherwise the standing heartbeat remains requi
    points there). Bring its branch to current `main`:
    `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
    git, ff-merge is the safe path — not `reset --hard`). Install dependencies with
-   your package manager after (the lockfile may have moved). A gitignored plan doc
-   survives the merge.
+   your package manager after (the lockfile may have moved). A plan doc the repository
+   ignores survives the merge; a tracked one may not (`/setup-workflow` offers those rules).
 5. **Run project setup steps (`§Setup`)** the later verify needs — e.g. a DB
    tunnel or service the live-verify depends on. Absent layer → start whatever your
    live-verify environment requires before Phase 4.
@@ -332,8 +332,8 @@ written · merge order documented.
 - **Release this run's slice claims.** A landed slice's PR supersedes its claim;
   for a pulled or abandoned slice remove the claim this run planted (unassign +
   `claim released` comment) so it stays grabbable. Foreign ones stay untouched.
-- **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
-  log, gitignored at worktree-root) and propagate each build-time assumption marker
+- **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions log at
+  the worktree root, **expected** to be ignored by git — `/setup-workflow` offers that rule) and propagate each build-time assumption marker
   to the sibling issue it carries. A hand-driven multi-PR / migration landing does
   NOT run `wrapup`'s assumption-propagation step — this is the only place it
   happens; `worktree remove` deletes the log.

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

@@ -37,6 +37,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, Workflow Advisories, and Safety Guardrails choices (Sections A4–A7) |
 | `.claude/settings.json` | additive activation of the advisory kit-origin Edit/Write hint (Section A8) |
 | user-local routing profile | familiar agent surfaces + switching autonomy (Section A9; never package- or repository-owned) |
+| `.gitignore` | **offered only** — one previewed, append-only marker block with the ignore rules for the planning artifacts the skills write (Section A11) |
 
 ## Idempotency contract — read before writing anything
 
@@ -405,6 +406,55 @@ machine, checkout path, repository name, credentials, or current GitHub login.
 Even a valid capability authorizes local preparation only; a pull request,
 push, publish, or merge remains a separate explicit approval.
 
+### 2j. Section A11 — Planning-artifact ignore rules (offered)
+
+> The planning skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and `ANNAHMEN.md`
+> into a session worktree. `.gitignore` is the consumer's file: the kit does not
+> own it and never touches it during `init` or `update`, so those artifacts are
+> ignored only if this repository already says so. Without the rules every
+> planning worktree reports a permanently dirty tree, the Worktree Lifecycle
+> cleanup refuses to remove it, and a plan doc can be committed by accident.
+
+Read the current state first. The preview is read-only and writes nothing:
+
+```bash
+python3 scripts/worktree-lifecycle/ignore_seed.py preview
+```
+
+- `nothing-to-do` — this repository already ignores every declared artifact.
+  Report it and ask nothing.
+- `blocked` — the marker block exists but no longer covers everything. That
+  block is consumer-owned: name the uncovered artifacts, let the user edit
+  `.gitignore` themselves, and never repair or rewrite it.
+- `append` — show the exact lines the preview printed, the whole marker block
+  verbatim and nothing summarized, then ask: *"Should setup add these ignore
+  rules to `.gitignore`?"*
+
+Offer exactly two choices:
+
+- **Add the rules** — run the seeder once. It appends that one marker block and
+  touches nothing else:
+
+```bash
+python3 scripts/worktree-lifecycle/ignore_seed.py apply
+```
+
+- **Not now** — write nothing. Explain that the planning skills still work, that
+  the artifacts will keep showing up as untracked changes, and that re-running
+  `/setup-workflow` offers this again.
+
+The write is append-only inside one idempotent marker block: it never rewrites,
+reorders, or removes an existing line; a re-run after an approval is a
+byte-identical no-op; and a decline leaves the file exactly as it was. An
+artifact already committed to history is reported separately — an ignore rule
+cannot untrack it, and setup never runs `git rm`. Only this explicit, approved
+step may write `.gitignore`; `init` and `update` reconciliation never reach the
+seeder.
+
+Report `appended · nothing to do (already ignored) · declined · blocked
+(consumer-edited block)`. After an approval — and only then — the Section A4
+`scratchPatterns` derivation has real ignored planning artefacts to read.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.

package/.agents/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

package/.claude/skills/grill-me/SKILL.md

@@ -52,7 +52,7 @@ For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-sta
 
 ## Plan-lock — writing PLAN.md
 
-Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
+Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root. `PLAN.md` is **expected** to be ignored by git so it never travels over git — the kit never edits your `.gitignore` by itself, but `/setup-workflow` offers to add that rule (consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
 
 ## Re-grill reconcile — execute-ready (Wave 26)
 

package/.claude/skills/grill-with-docs/SKILL.md

@@ -40,7 +40,7 @@ For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-sta
 
 ## Plan-lock — writing PLAN.md
 
-Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
+Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root. `PLAN.md` is **expected** to be ignored by git so it never travels over git — the kit never edits your `.gitignore` by itself, but `/setup-workflow` offers to add that rule (consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
 
 </plan-lock>
 

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

@@ -146,8 +146,8 @@ replace the ~30-second heartbeat; otherwise the standing heartbeat remains requi
    points there). Bring its branch to current `main`:
    `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
    git, ff-merge is the safe path — not `reset --hard`). Install dependencies with
-   your package manager after (the lockfile may have moved). A gitignored plan doc
-   survives the merge.
+   your package manager after (the lockfile may have moved). A plan doc the repository
+   ignores survives the merge; a tracked one may not (`/setup-workflow` offers those rules).
 5. **Run project setup steps (`§Setup`)** the later verify needs — e.g. a DB
    tunnel or service the live-verify depends on. Absent layer → start whatever your
    live-verify environment requires before Phase 4.
@@ -332,8 +332,8 @@ written · merge order documented.
 - **Release this run's slice claims.** A landed slice's PR supersedes its claim;
   for a pulled or abandoned slice remove the claim this run planted (unassign +
   `claim released` comment) so it stays grabbable. Foreign ones stay untouched.
-- **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
-  log, gitignored at worktree-root) and propagate each build-time assumption marker
+- **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions log at
+  the worktree root, **expected** to be ignored by git — `/setup-workflow` offers that rule) and propagate each build-time assumption marker
   to the sibling issue it carries. A hand-driven multi-PR / migration landing does
   NOT run `wrapup`'s assumption-propagation step — this is the only place it
   happens; `worktree remove` deletes the log.

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

@@ -37,6 +37,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, Workflow Advisories, and Safety Guardrails choices (Sections A4–A7) |
 | `.claude/settings.json` | additive activation of the advisory kit-origin Edit/Write hint (Section A8) |
 | user-local routing profile | familiar agent surfaces + switching autonomy (Section A9; never package- or repository-owned) |
+| `.gitignore` | **offered only** — one previewed, append-only marker block with the ignore rules for the planning artifacts the skills write (Section A11) |
 
 ## Idempotency contract — read before writing anything
 
@@ -405,6 +406,55 @@ machine, checkout path, repository name, credentials, or current GitHub login.
 Even a valid capability authorizes local preparation only; a pull request,
 push, publish, or merge remains a separate explicit approval.
 
+### 2j. Section A11 — Planning-artifact ignore rules (offered)
+
+> The planning skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and `ANNAHMEN.md`
+> into a session worktree. `.gitignore` is the consumer's file: the kit does not
+> own it and never touches it during `init` or `update`, so those artifacts are
+> ignored only if this repository already says so. Without the rules every
+> planning worktree reports a permanently dirty tree, the Worktree Lifecycle
+> cleanup refuses to remove it, and a plan doc can be committed by accident.
+
+Read the current state first. The preview is read-only and writes nothing:
+
+```bash
+python3 scripts/worktree-lifecycle/ignore_seed.py preview
+```
+
+- `nothing-to-do` — this repository already ignores every declared artifact.
+  Report it and ask nothing.
+- `blocked` — the marker block exists but no longer covers everything. That
+  block is consumer-owned: name the uncovered artifacts, let the user edit
+  `.gitignore` themselves, and never repair or rewrite it.
+- `append` — show the exact lines the preview printed, the whole marker block
+  verbatim and nothing summarized, then ask: *"Should setup add these ignore
+  rules to `.gitignore`?"*
+
+Offer exactly two choices:
+
+- **Add the rules** — run the seeder once. It appends that one marker block and
+  touches nothing else:
+
+```bash
+python3 scripts/worktree-lifecycle/ignore_seed.py apply
+```
+
+- **Not now** — write nothing. Explain that the planning skills still work, that
+  the artifacts will keep showing up as untracked changes, and that re-running
+  `/setup-workflow` offers this again.
+
+The write is append-only inside one idempotent marker block: it never rewrites,
+reorders, or removes an existing line; a re-run after an approval is a
+byte-identical no-op; and a decline leaves the file exactly as it was. An
+artifact already committed to history is reported separately — an ignore rule
+cannot untrack it, and setup never runs `git rm`. Only this explicit, approved
+step may write `.gitignore`; `init` and `update` reconciliation never reach the
+seeder.
+
+Report `appended · nothing to do (already ignored) · declined · blocked
+(consumer-edited block)`. After an approval — and only then — the Section A4
+`scratchPatterns` derivation has real ignored planning artefacts to read.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.

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

package/README.md

@@ -469,6 +469,31 @@ 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.

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.39.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"
     },
@@ -447,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
+      "sha256": "fab4fb2f4d6fee820c9b7a737fa955a5ea2cd398987246bd7a04c5fba2c75b26",
       "mode": 420,
       "origin": "kit"
     },
@@ -687,7 +687,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "4ef2a06e17e08f0fc0c5cc09e4414af67a186a73ca7634e8c378aab5b5638274",
+      "sha256": "29c61411aa42a3f456b3f27fdd15552654b64ef2d72b321bc9c9e11229745626",
       "mode": 420,
       "origin": "kit"
     },
@@ -757,7 +757,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "bf68e0a80b212159f6838bc2bcd3e85714a70cceeff55ed019f87246175182e7",
+      "sha256": "f9fb7ef6d4f4e1ed603a5a480d8f97508fd6c99def8194c7ba0a95c62fd3c743",
       "mode": 420,
       "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"
     },
@@ -1769,7 +1769,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "02862cd5e7e07a5f06dad89792fcebd0a6c17cf2216a27c7e0f724026fdda53a",
+      "sha256": "fab4fb2f4d6fee820c9b7a737fa955a5ea2cd398987246bd7a04c5fba2c75b26",
       "mode": 420,
       "origin": "kit"
     },
@@ -2029,7 +2029,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "4ef2a06e17e08f0fc0c5cc09e4414af67a186a73ca7634e8c378aab5b5638274",
+      "sha256": "29c61411aa42a3f456b3f27fdd15552654b64ef2d72b321bc9c9e11229745626",
       "mode": 420,
       "origin": "kit"
     },
@@ -2099,7 +2099,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "bf68e0a80b212159f6838bc2bcd3e85714a70cceeff55ed019f87246175182e7",
+      "sha256": "f9fb7ef6d4f4e1ed603a5a480d8f97508fd6c99def8194c7ba0a95c62fd3c743",
       "mode": 420,
       "origin": "kit"
     },
@@ -2815,6 +2815,22 @@
       "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"
+    },
     {
       "path": "scripts/worktree-lifecycle/profile.py",
       "kind": "script",
@@ -2827,7 +2843,7 @@
       "path": "scripts/worktree-lifecycle/README.md",
       "kind": "doc",
       "installRole": "consumer",
-      "sha256": "91cfa8ebb74872ccec1160c0a7b28edcfacea3217900805034dca0f0c8f39c05",
+      "sha256": "0dbba4a87d41171f3fce22a4842eecd2a989ea6a5ddf44832d7b2aed9feb4226",
       "mode": 420,
       "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.39.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": {

package/scripts/test_worktree_ignore_seed.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""Consumer ignore-gap contract (#255).
+
+Shipped skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and `ANNAHMEN.md` into a
+session worktree, but `.gitignore` is a consumer file the kit does not own, so
+`init`/`update` never seed the matching rules. ADR 0008 resolves the gap two
+ways, and both are pinned here:
+
+1. `/setup-workflow` may **offer** the rules through
+   `scripts/worktree-lifecycle/ignore_seed.py`. The helper is append-only
+   inside one idempotent marker block: it never rewrites, reorders, or removes
+   an existing line, it is a no-op on re-run, and it is unreachable from
+   `init`/`update` reconciliation.
+2. Shipped skill prose states the assumption instead of asserting the ignore
+   state as a fact the kit cannot guarantee.
+
+Run: python3 scripts/test_worktree_ignore_seed.py
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+LIFECYCLE = REPO / "scripts/worktree-lifecycle"
+HELPER = LIFECYCLE / "ignore_seed.py"
+ARTIFACT_MANIFEST = LIFECYCLE / "plan-artifacts.json"
+SKILL_TREES = (REPO / ".claude/skills", REPO / ".agents/skills")
+
+
+def load_helper():
+    spec = importlib.util.spec_from_file_location("wl_ignore_seed", HELPER)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", *args], cwd=repo, capture_output=True, text=True, check=True,
+    )
+
+
+def make_repo(stack, gitignore: str | None = None) -> Path:
+    repo = Path(stack.enter_context(tempfile.TemporaryDirectory()))
+    git(repo, "init", "-q")
+    git(repo, "config", "user.email", "test@example.com")
+    git(repo, "config", "user.name", "test")
+    if gitignore is not None:
+        (repo / ".gitignore").write_text(gitignore, encoding="utf-8")
+    return repo
+
+
+class ArtifactManifestTest(unittest.TestCase):
+    """The kit declares which planning artifacts its own skills write."""
+
+    def test_manifest_declares_the_three_planning_artifacts(self):
+        document = json.loads(ARTIFACT_MANIFEST.read_text(encoding="utf-8"))
+        paths = [entry["path"] for entry in document["artifacts"]]
+        self.assertEqual(
+            paths, ["PLAN.md", "PLAN-REVIEW-LOG.md", "ANNAHMEN.md"],
+        )
+        for entry in document["artifacts"]:
+            self.assertTrue(entry["writtenBy"], entry["path"])
+
+
+class PlanTest(unittest.TestCase):
+    """`plan()` reports the exact append, never a rewrite."""
+
+    def setUp(self):
+        self.helper = load_helper()
+        self.stack = __import__("contextlib").ExitStack()
+        self.addCleanup(self.stack.close)
+
+    def test_fresh_repo_lists_every_artifact_as_pending(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        plan = self.helper.plan(repo)
+        self.assertEqual(
+            plan.pending, ("PLAN.md", "PLAN-REVIEW-LOG.md", "ANNAHMEN.md"),
+        )
+        self.assertEqual(plan.already_ignored, ())
+        self.assertEqual(plan.status, "append")
+        for path in plan.pending:
+            self.assertIn(f"\n{path}\n", plan.block)
+        self.assertTrue(plan.block.startswith(self.helper.BLOCK_START))
+        self.assertTrue(plan.block.rstrip("\n").endswith(self.helper.BLOCK_END))
+
+    def test_missing_gitignore_is_reported_as_a_create(self):
+        repo = make_repo(self.stack)
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.status, "append")
+        self.assertFalse(plan.gitignore_exists)
+
+    def test_consumer_rules_already_covering_everything_are_nothing_to_do(self):
+        repo = make_repo(
+            self.stack, "PLAN.md\nPLAN-REVIEW-LOG.md\nANNAHMEN.md\n",
+        )
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.pending, ())
+        self.assertEqual(plan.status, "nothing-to-do")
+        self.assertIsNone(plan.block)
+
+    def test_partial_coverage_pends_only_the_missing_rules(self):
+        repo = make_repo(self.stack, "PLAN.md\n")
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.pending, ("PLAN-REVIEW-LOG.md", "ANNAHMEN.md"))
+        self.assertEqual(plan.already_ignored, ("PLAN.md",))
+        self.assertNotIn("\nPLAN.md\n", plan.block)
+
+    def test_a_wildcard_consumer_rule_counts_as_covered(self):
+        repo = make_repo(self.stack, "*.md\n")
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.pending, ())
+
+    def test_a_tracked_artifact_is_named_because_a_rule_cannot_untrack_it(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        (repo / "PLAN.md").write_text("plan\n", encoding="utf-8")
+        git(repo, "add", "PLAN.md")
+        git(repo, "commit", "-qm", "add plan")
+        plan = self.helper.plan(repo)
+        self.assertEqual(plan.tracked, ("PLAN.md",))
+        self.assertIn("PLAN.md", plan.pending)
+
+
+class ApplyTest(unittest.TestCase):
+    """`apply()` is append-only, idempotent, and never rewrites."""
+
+    def setUp(self):
+        self.helper = load_helper()
+        self.stack = __import__("contextlib").ExitStack()
+        self.addCleanup(self.stack.close)
+
+    def test_apply_appends_and_preserves_the_existing_bytes_verbatim(self):
+        original = "node_modules/\n\n# my rules\ndist/\n"
+        repo = make_repo(self.stack, original)
+        result = self.helper.apply(repo)
+        self.assertEqual(result.status, "appended")
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        self.assertTrue(text.startswith(original))
+        self.assertIn(self.helper.BLOCK_START, text)
+        for path in ("PLAN.md", "PLAN-REVIEW-LOG.md", "ANNAHMEN.md"):
+            self.assertIn(f"\n{path}\n", text)
+
+    def test_rerun_is_a_byte_identical_no_op(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        self.helper.apply(repo)
+        first = (repo / ".gitignore").read_bytes()
+        second_result = self.helper.apply(repo)
+        self.assertEqual(second_result.status, "nothing-to-do")
+        self.assertEqual((repo / ".gitignore").read_bytes(), first)
+        self.assertEqual(first.decode().count(self.helper.BLOCK_START), 1)
+
+    def test_decline_path_writes_nothing(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        before = (repo / ".gitignore").read_bytes()
+        self.helper.plan(repo)
+        self.assertEqual((repo / ".gitignore").read_bytes(), before)
+
+    def test_already_covered_repo_is_left_untouched(self):
+        original = "PLAN.md\nPLAN-REVIEW-LOG.md\nANNAHMEN.md\n"
+        repo = make_repo(self.stack, original)
+        result = self.helper.apply(repo)
+        self.assertEqual(result.status, "nothing-to-do")
+        self.assertEqual(
+            (repo / ".gitignore").read_text(encoding="utf-8"), original,
+        )
+
+    def test_missing_gitignore_is_created_with_only_the_block(self):
+        repo = make_repo(self.stack)
+        self.helper.apply(repo)
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        self.assertTrue(text.startswith(self.helper.BLOCK_START))
+
+    def test_an_edited_marker_block_blocks_instead_of_rewriting(self):
+        repo = make_repo(self.stack)
+        self.helper.apply(repo)
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        edited = text.replace("ANNAHMEN.md\n", "")
+        (repo / ".gitignore").write_text(edited, encoding="utf-8")
+        result = self.helper.apply(repo)
+        self.assertEqual(result.status, "blocked")
+        self.assertEqual(
+            (repo / ".gitignore").read_text(encoding="utf-8"), edited,
+        )
+        self.assertEqual(edited.count(self.helper.BLOCK_START), 1)
+
+    def test_cli_preview_writes_nothing_and_reports_json(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        before = (repo / ".gitignore").read_bytes()
+        result = subprocess.run(
+            [sys.executable, str(HELPER), "preview", "--repo", str(repo), "--json"],
+            capture_output=True, text=True,
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "append")
+        self.assertEqual((repo / ".gitignore").read_bytes(), before)
+
+    def test_cli_apply_exits_zero_and_is_idempotent(self):
+        repo = make_repo(self.stack, "node_modules/\n")
+        for _ in range(2):
+            result = subprocess.run(
+                [sys.executable, str(HELPER), "apply", "--repo", str(repo)],
+                capture_output=True, text=True,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+        text = (repo / ".gitignore").read_text(encoding="utf-8")
+        self.assertEqual(text.count(self.helper.BLOCK_START), 1)
+
+
+class ReconciliationBoundaryTest(unittest.TestCase):
+    """Only setup-workflow may reach the seeder; never init/update."""
+
+    def test_no_installer_command_invokes_the_seeder(self):
+        # bundle.mjs only DECLARES the file as shipped; every other installer
+        # module must not know the seeder exists.
+        declaration = REPO / "src/lib/bundle.mjs"
+        offenders = []
+        for path in sorted((REPO / "src").rglob("*.mjs")):
+            if path == declaration:
+                continue
+            if "ignore_seed" in path.read_text(encoding="utf-8"):
+                offenders.append(str(path.relative_to(REPO)))
+        self.assertEqual(offenders, [])
+
+    def test_the_seeder_ships_with_the_kit(self):
+        bundle = (REPO / "src/lib/bundle.mjs").read_text(encoding="utf-8")
+        self.assertIn("scripts/worktree-lifecycle/ignore_seed.py", bundle)
+        self.assertIn("scripts/worktree-lifecycle/plan-artifacts.json", bundle)
+
+
+class SetupWorkflowOfferTest(unittest.TestCase):
+    """The offer is an explicit, previewed, declinable setup step."""
+
+    def _skill(self, tree: Path) -> str:
+        return (tree / "setup-workflow/SKILL.md").read_text(encoding="utf-8")
+
+    def _seed(self, tree: Path) -> str:
+        return (tree / "setup-workflow/worktree-lifecycle.md").read_text(
+            encoding="utf-8",
+        )
+
+    def test_both_surfaces_document_the_previewed_offer(self):
+        for tree in SKILL_TREES:
+            body = self._skill(tree)
+            self.assertIn(
+                "python3 scripts/worktree-lifecycle/ignore_seed.py preview", body,
+            )
+            self.assertIn(
+                "python3 scripts/worktree-lifecycle/ignore_seed.py apply", body,
+            )
+            flat = re.sub(r"\s+", " ", body)
+            self.assertIn("Add the rules", flat)
+            self.assertIn("Not now", flat)
+
+    def test_the_seed_contract_carries_the_ignore_offer_matrix(self):
+        for tree in SKILL_TREES:
+            flat = re.sub(r"\s+", " ", self._seed(tree))
+            self.assertIn("ignore_seed.py", flat)
+            for row in ("approve", "decline", "already ignored", "re-run"):
+                self.assertIn(row, flat)
+
+
+class ProseClaimCensusTest(unittest.TestCase):
+    """No shipped skill asserts an ignore state the kit cannot guarantee."""
+
+    ARTIFACT = re.compile(
+        r"PLAN\.md|PLAN-REVIEW-LOG\.md|ANNAHMEN\.md|plan doc|assumptions log",
+        re.IGNORECASE,
+    )
+    # Unconditional assertions of the ignore state. Conditional or hedged
+    # wording ("a project may gitignore these files", "when `PLAN.md` is
+    # ignored") is deliberately allowed.
+    FORBIDDEN = (
+        re.compile(r"\(gitignored\b", re.IGNORECASE),
+        re.compile(r"\b(?:is|are|stays?|remains?)\s+gitignored\b", re.IGNORECASE),
+        re.compile(r"\bgitignored\s+(?:at|in|since)\b", re.IGNORECASE),
+        re.compile(r"\ba\s+gitignored\s+plan\s+doc\b", re.IGNORECASE),
+        re.compile(r"\bgitignored,\s*on-disk only\b", re.IGNORECASE),
+    )
+    WINDOW = 160
+
+    def _claim_offenders(self):
+        offenders = []
+        for tree in SKILL_TREES:
+            for path in sorted(tree.rglob("*.md")):
+                flat = re.sub(r"\s+", " ", path.read_text(encoding="utf-8"))
+                for pattern in self.FORBIDDEN:
+                    for match in pattern.finditer(flat):
+                        window = flat[
+                            max(0, match.start() - self.WINDOW):
+                            match.end() + self.WINDOW
+                        ]
+                        if self.ARTIFACT.search(window):
+                            offenders.append(
+                                f"{path.relative_to(REPO)}: {match.group(0)}"
+                            )
+        return sorted(set(offenders))
+
+    def test_no_skill_states_the_ignore_rule_as_an_installed_fact(self):
+        self.assertEqual(self._claim_offenders(), [])
+
+    def test_the_replacement_wording_names_who_can_make_it_true(self):
+        for name in ("grill-me", "grill-with-docs", "orchestrate-wave"):
+            for tree in SKILL_TREES:
+                body = (tree / name / "SKILL.md").read_text(encoding="utf-8")
+                flat = re.sub(r"\s+", " ", body)
+                self.assertIn("setup-workflow", flat, f"{tree}/{name}")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/worktree-lifecycle/README.md

@@ -58,6 +58,24 @@ the core proves the target is unsafe.
 | `enforce-worktree-discipline.py` | PreToolUse | routes issue-branch creation through the configured setup entry |
 | `slice-handoff-hint.py` | UserPromptSubmit | names the configured setup entry for a defined slice |
 
+## Planning-artifact ignore rules
+
+`plan-artifacts.json` is the kit-owned declaration of the planning artefacts the
+shipped skills write (`PLAN.md`, `PLAN-REVIEW-LOG.md`, `ANNAHMEN.md`).
+`ignore_seed.py` turns that declaration into an offer, never an installation:
+`preview` reports what an approval would append and writes nothing, and `apply`
+appends exactly one marker block. `.gitignore` is a consumer file the kit does
+not own, so only an explicit approved `/setup-workflow` step may run `apply`;
+`init` and `update` reconciliation never reach it (ADR 0008).
+
+The append never rewrites, reorders, or removes an existing line. A repository
+that already ignores every artefact reports `nothing-to-do`, a re-run after an
+approval is a byte-identical no-op, and a marker block the consumer has since
+edited reports `blocked` rather than being repaired. An artefact already tracked
+in git is named separately — an ignore rule cannot untrack it, and the helper
+never runs `git rm`. Only after such an approval does the `scratchPatterns`
+derivation have real ignored planning artefacts to read.
+
 ## Cleanup
 
 `cleanup.py` previews by default. Removal refuses protected, tracked-dirty,

package/scripts/worktree-lifecycle/ignore_seed.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Offer the planning-artifact ignore rules for a consumer `.gitignore`.
+
+The shipped skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and `ANNAHMEN.md`
+into a session worktree, but `.gitignore` is a consumer file the kit does not
+own: `init` and `update` never touch it. This helper is the one place that
+closes that gap, and it closes it only when a user explicitly approves the
+offer inside `/setup-workflow` (ADR 0008).
+
+Contract:
+
+- `preview` reads and reports; it never writes.
+- `apply` appends one marker block and nothing else. It never rewrites,
+  reorders, or removes an existing line, so a second run is a byte-identical
+  no-op once the rules are in place.
+- Rules a consumer already has — by any pattern, including a wildcard — are
+  reported as covered and never duplicated.
+- A marker block that the consumer has since edited is theirs: the helper
+  blocks instead of repairing it.
+- Nothing here runs during `init`/`update` reconciliation.
+
+Usage:
+  python3 scripts/worktree-lifecycle/ignore_seed.py preview [--repo PATH] [--json]
+  python3 scripts/worktree-lifecycle/ignore_seed.py apply   [--repo PATH] [--json]
+
+Exit codes: 0 previewed/appended/nothing-to-do · 2 blocked · 1 error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+MANIFEST = Path(__file__).resolve().parent / "plan-artifacts.json"
+
+BLOCK_START = "# >>> agent-workflow-kit: planning-artifacts/v1 >>>"
+BLOCK_END = "# <<< agent-workflow-kit: planning-artifacts/v1 <<<"
+BLOCK_NOTE = (
+    "# Planning artifacts the agent workflow skills write into a session\n"
+    "# worktree. They are session scratch, never part of the change. Added by\n"
+    "# setup-workflow on request; this block is yours to edit or delete.\n"
+)
+
+
+class IgnoreSeedError(RuntimeError):
+    """A safe, user-visible refusal."""
+
+
+@dataclass(frozen=True)
+class IgnorePlan:
+    """What an approval would append — and nothing more."""
+
+    repo: Path
+    gitignore_exists: bool
+    already_ignored: tuple[str, ...]
+    pending: tuple[str, ...]
+    tracked: tuple[str, ...]
+    block: str | None
+    status: str
+    detail: str
+
+    def as_dict(self) -> dict:
+        return {
+            "status": self.status,
+            "detail": self.detail,
+            "gitignoreExists": self.gitignore_exists,
+            "alreadyIgnored": list(self.already_ignored),
+            "pending": list(self.pending),
+            "tracked": list(self.tracked),
+            "block": self.block,
+        }
+
+
+def load_artifacts(manifest: Path = MANIFEST) -> tuple[str, ...]:
+    """Return the kit-declared planning artifacts, in declaration order."""
+    try:
+        document = json.loads(manifest.read_text(encoding="utf-8"))
+        return tuple(entry["path"] for entry in document["artifacts"])
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as error:
+        raise IgnoreSeedError(f"cannot read planning-artifact manifest: {error}") from error
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            ["git", *args], cwd=repo, capture_output=True, text=True,
+        )
+    except OSError as error:  # pragma: no cover - git absent
+        raise IgnoreSeedError(f"cannot run git: {error}") from error
+
+
+def is_ignored(repo: Path, path: str) -> bool:
+    """True when any ignore rule already matches `path`.
+
+    `--no-index` asks the pattern question, not the index question, so an
+    artifact that a consumer once committed still reports its real rule state.
+    """
+    return _git(repo, "check-ignore", "-q", "--no-index", "--", path).returncode == 0
+
+
+def is_tracked(repo: Path, path: str) -> bool:
+    """True when the artifact is committed — an ignore rule cannot untrack it."""
+    result = _git(repo, "ls-files", "--error-unmatch", "--", path)
+    return result.returncode == 0
+
+
+def render_block(paths: tuple[str, ...]) -> str:
+    """The exact text an approval appends."""
+    listed = "".join(f"{path}\n" for path in paths)
+    return f"{BLOCK_START}\n{BLOCK_NOTE}{listed}{BLOCK_END}\n"
+
+
+def _read_gitignore(repo: Path) -> tuple[bool, str]:
+    target = repo / ".gitignore"
+    try:
+        return True, target.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return False, ""
+    except OSError as error:
+        raise IgnoreSeedError(f"cannot read {target}: {error}") from error
+
+
+def plan(repo: Path, manifest: Path = MANIFEST) -> IgnorePlan:
+    """Report what an approval would change. Reads only."""
+    repo = Path(repo)
+    if not (repo / ".git").exists():
+        raise IgnoreSeedError(f"not a git repository: {repo}")
+    artifacts = load_artifacts(manifest)
+    exists, text = _read_gitignore(repo)
+    covered = tuple(path for path in artifacts if is_ignored(repo, path))
+    pending = tuple(path for path in artifacts if path not in covered)
+    tracked = tuple(path for path in artifacts if is_tracked(repo, path))
+    has_block = BLOCK_START in text
+
+    if not pending:
+        return IgnorePlan(
+            repo=repo, gitignore_exists=exists, already_ignored=covered,
+            pending=(), tracked=tracked, block=None, status="nothing-to-do",
+            detail="every planning artifact is already ignored",
+        )
+    if has_block:
+        return IgnorePlan(
+            repo=repo, gitignore_exists=exists, already_ignored=covered,
+            pending=pending, tracked=tracked, block=None, status="blocked",
+            detail=(
+                "the marker block exists but no longer covers "
+                f"{', '.join(pending)} — that block is consumer-owned; "
+                "edit .gitignore yourself"
+            ),
+        )
+    return IgnorePlan(
+        repo=repo, gitignore_exists=exists, already_ignored=covered,
+        pending=pending, tracked=tracked, block=render_block(pending),
+        status="append",
+        detail=f"would append {len(pending)} rule(s) in one marker block",
+    )
+
+
+def apply(repo: Path, manifest: Path = MANIFEST) -> IgnorePlan:
+    """Append the previewed block. Never rewrites an existing line."""
+    decision = plan(repo, manifest)
+    if decision.status != "append":
+        return decision
+    target = Path(repo) / ".gitignore"
+    _, text = _read_gitignore(Path(repo))
+    prefix = text
+    if prefix and not prefix.endswith("\n"):
+        prefix += "\n"
+    if prefix and not prefix.endswith("\n\n"):
+        prefix += "\n"
+    try:
+        target.write_text(prefix + decision.block, encoding="utf-8")
+    except OSError as error:
+        raise IgnoreSeedError(f"cannot write {target}: {error}") from error
+    return IgnorePlan(
+        repo=decision.repo, gitignore_exists=True,
+        already_ignored=decision.already_ignored, pending=decision.pending,
+        tracked=decision.tracked, block=decision.block, status="appended",
+        detail=f"appended {len(decision.pending)} rule(s) to .gitignore",
+    )
+
+
+def _report(decision: IgnorePlan, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(decision.as_dict(), indent=2))
+        return
+    print(f"{decision.status} — {decision.detail}")
+    if decision.already_ignored:
+        print(f"  already ignored: {', '.join(decision.already_ignored)}")
+    if decision.tracked:
+        print(
+            "  tracked in git (an ignore rule cannot untrack these): "
+            f"{', '.join(decision.tracked)}"
+        )
+    if decision.block:
+        label = "appended" if decision.status == "appended" else "would append"
+        print(f"  {label}:")
+        for line in decision.block.rstrip("\n").split("\n"):
+            print(f"    {line}")
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="ignore_seed.py")
+    parser.add_argument("command", choices=("preview", "apply"))
+    parser.add_argument("--repo", default=".")
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    try:
+        decision = plan(args.repo) if args.command == "preview" else apply(args.repo)
+    except IgnoreSeedError as error:
+        print(str(error), file=sys.stderr)
+        return 1
+    _report(decision, as_json=args.json)
+    return 2 if decision.status == "blocked" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/worktree-lifecycle/plan-artifacts.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "artifacts": [
+    {
+      "path": "PLAN.md",
+      "writtenBy": [
+        "grill-me",
+        "grill-with-docs",
+        "codex-review",
+        "grill-me-codex",
+        "grill-with-docs-codex",
+        "codex-build",
+        "orchestrate-wave"
+      ],
+      "why": "the locked plan a planning session hands to the implementing session"
+    },
+    {
+      "path": "PLAN-REVIEW-LOG.md",
+      "writtenBy": [
+        "codex-review",
+        "grill-me-codex",
+        "grill-with-docs-codex",
+        "codex-build"
+      ],
+      "why": "the append-only cross-model review transcript of that plan"
+    },
+    {
+      "path": "ANNAHMEN.md",
+      "writtenBy": [
+        "tdd",
+        "orchestrate-wave",
+        "wrapup"
+      ],
+      "why": "the build-time assumption-drift log wrapup propagates before teardown"
+    }
+  ]
+}

package/src/lib/bundle.mjs

@@ -147,6 +147,12 @@ export const HELPER_FILES = [
   { path: 'scripts/worktree-lifecycle/session.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/worktree-lifecycle/capabilities.json', kind: 'doc', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/README.md', kind: 'doc', mode: 0o644 },
+  // Offered planning-artifact ignore rules for /setup-workflow Section A11.
+  // `.gitignore` is consumer-owned, so only an approved setup step may append
+  // the block — init/update reconciliation never reach this. plan-artifacts.json
+  // is the kit-owned declaration it reads. Invokable CLI → 0o755.
+  { path: 'scripts/worktree-lifecycle/plan-artifacts.json', kind: 'doc', mode: 0o644 },
+  { path: 'scripts/worktree-lifecycle/ignore_seed.py', kind: 'script', mode: 0o755 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.