@ikon85/agent-workflow-kit 0.38.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/kit-update/SKILL.md

@@ -105,6 +105,19 @@ release contain the same artifact.
    and safe routes—never file content. Automated update pull
    requests carry the same availability summary and remain manual-merge only.
 
+   Read the required consumer migrations alongside the file delta. A release
+   that forces the Consumer to commit a decision registers it as declarative,
+   versioned data in the Kit's migration registry — never as release-note prose.
+   Preview and the terminal report expose the same structured record, so an
+   interactive run, a `--yes` run, `update --json`, and the automated update
+   pull request all name the same outstanding actions. Each action names the
+   workflow that resolves it, the Consumer file that carries the decision, and
+   the exact missing decision. `kit-update` only detects and reports it: it
+   never writes the decision, never infers a value, and never invents or
+   auto-accepts a pattern that would grant deletion authority. An empty but
+   explicit decision is a committed decision and clears the action; a missing
+   one keeps it pending on every rerun.
+
    For each conflicted kit-shipped file, always ask the user whether the local
    edit is a generic improvement or project-specific; never decide or act
    automatically. For a generic improvement retained as a bridge, run
@@ -131,7 +144,26 @@ release contain the same artifact.
    resume the transaction through the update API's `resumeFrom` option. Do not
    copy staged files into the consumer by hand.
 
-5. Check the optional project census after the update:
+5. Review the consumer profile's glob dialect after the update:
+
+   ```sh
+   python3 scripts/profile_globs.py docs/agents/workflow-capabilities.json
+   ```
+
+   Every consumer-profile glob — Worktree Lifecycle `scratchPatterns` and
+   `wrapup.landingGeneratedArtifactPatterns`, Workflow Advisories
+   `baseline.sourceGlobs` and the `preRefactor`/`stopChecks` surface globs — is
+   matched by one shared repository-relative dialect. A pattern written for an
+   older matcher can narrow or widen. The check names each such pattern with
+   the witness path that proves the difference and marks the keys that carry
+   deletion authority; exit code 1 means at least one needs review. Report the
+   named patterns and let the user rewrite them. The updater never rewrites a
+   consumer pattern, and a widened deletion-authority pattern is never accepted
+   silently — an update must not expand what cleanup may remove. A missing or
+   disabled profile leaves nothing to review and does not invalidate the
+   update.
+
+6. Check the optional project census after the update:
 
    ```sh
    python3 .claude/hooks/drift-guard.py --census-status

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
 
@@ -216,6 +217,15 @@ Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
 - **Disable** — remove only the exact kit-owned hook commands first, then set
   `enabled: false`; retain the profile, setup policy, and unknown keys.
 
+Whenever a profile already carries patterns — on **Yes** over an existing
+section and on **Existing** — run
+`python3 scripts/profile_globs.py docs/agents/workflow-capabilities.json` and
+report every pattern it names. Patterns whose match set narrows or widens under
+the shared dialect are a consumer decision: name them with their witness path,
+mark the deletion-authority keys, and let the consumer rewrite them. Never
+rewrite a pattern for them, and never accept a widened deletion-authority
+pattern silently.
+
 The default setup entry is
 `python3 scripts/worktree-lifecycle/setup.py`; a proven consumer-native helper
 may remain the configured `setupEntry` for parity. The handoff advisory always
@@ -273,6 +283,12 @@ repository?"* Offer exactly **Yes**, **Later**, and **No**.
 - **Disable** — remove exact kit-owned commands first, then set `enabled:
   false`; preserve every profile value and unknown key.
 
+`baseline.sourceGlobs` and the `preRefactor`/`stopChecks` surface globs use the
+same shared dialect as the Worktree Lifecycle patterns above. An adopted
+profile written for the older whole-string matcher can change meaning, so run
+`python3 scripts/profile_globs.py docs/agents/workflow-capabilities.json` and
+report every pattern it names before treating the section as reconciled.
+
 ### 2f. Section A7 — Optional Safety Guardrails
 
 > Safety Guardrails is a counted group of seven independently selectable
@@ -390,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.
@@ -411,13 +476,29 @@ Seed `docs/agents/domain.md` from [domain.md](./domain.md).
 
 **Skip entirely if Section A is not GitHub** → write `board-sync.md` with `state=not-applicable`, `mode=none`, a one-line "this project does not use a GitHub-Projects board" note. Terminal; never re-prompts.
 
-**Preflight:** `gh auth status`. If `project`/`read:project` scope is missing, surface the exact remedy: `gh auth refresh -s project,read:project`, then fall through to the stub path below.
+**Preflight:** `gh auth status` (or `python3 scripts/board_bootstrap.py preflight --json` for the machine-readable answer). If `project`/`read:project` scope is missing, surface the exact remedy: `gh auth refresh -s project,read:project`, then fall through to the stub path below — without the write scope, never attempt creation.
 
-**Discover (the success path):** `gh project list --owner <remote-owner> --format json`. If **exactly one** project clearly belongs to this repo's owner, read its fields: `gh project field-list <number> --owner <owner> --format json`. Record each field's `id`, `name`, `dataType` (single-select / number / text), and for single-selects the option `id`s. Write `board-sync.md` with `state=filled`, `mode=github-projects-v2`, the project node id + repo + the discovered field/option IDs, seeded from [board-sync.md](./board-sync.md). Fill the `<!-- board-sync:profile -->` **JSON block** (the machine SSOT `scripts/board_config.py` parses) — replace each `<…>` placeholder under `repo`/`project`/`fields` with the discovered value; leave the convention values (`labels`/`branchPrefixes`/`prMarkers`/`headings`) at their seeded defaults unless this project's conventions differ.
+**Discover (the existing-board path):** `gh project list --owner <remote-owner> --format json`. If **exactly one** project clearly belongs to this repo's owner, read its fields: `gh project field-list <number> --owner <owner> --format json`. Record each field's `id`, `name`, `dataType` (single-select / number / text), and for single-selects the option `id`s. Write `board-sync.md` with `state=filled`, `mode=github-projects-v2`, the project node id + repo + the discovered field/option IDs, seeded from [board-sync.md](./board-sync.md). Fill the `<!-- board-sync:profile -->` **JSON block** (the machine SSOT `scripts/board_config.py` parses) — replace each `<…>` placeholder under `repo`/`project`/`fields` with the discovered value; leave the convention values (`labels`/`branchPrefixes`/`prMarkers`/`headings`) at their seeded defaults unless this project's conventions differ.
 
 **Map the status roles (`fields.status.roles`):** the seeded map carries the recommended English stage names (`Idea/Triaged/Spec/In Progress/Review/Done`). Reconcile it against the **discovered** Status option names: an exact (case-sensitive) match keeps its seeded entry; for every role whose seeded name is NOT among the discovered options, ask the user which of their actual option names plays that role (a stage they don't have may be omitted from the map — say so). Never guess a mapping from similarity. Finish with a validation pass: every role value in the map MUST appear in `fields.status.options`, else fix before writing `state=filled`.
 
-**Fallback (the single catch-all — no board / >1 / ambiguous / scope error / read failure):** do **not** auto-create a board (`gh project create` alone cannot provision the Status options + workflow fields a board needs). Write `board-sync.md` with `state=stub`, `mode=github-projects-v2`, and inline **instructions**: which fields the workflow profile needs (a Status single-select with your stage options; optionally a Wave number, a Cluster text, a Spec-Path / Plan-Path text), how to create the board in the GitHub UI / `gh`, and "then run `/setup-workflow` again — it will discover and fill the IDs." Retryable.
+**Offer creation (no board found, scope present):** a fresh repo can reach a working board in this run — `gh project create` provisions the shell and `gh project field-create --single-select-options` provisions the Status single-select together with its options. Minting a GitHub Project is an outward, user-visible action, so **ask first and never create a board without an explicit yes**. Name the stage options the board will get (the seed's `fields.status.roles` values) in the question, and edit those role values in the seed *before* creating if the user wants a different stage vocabulary — they become the board's Status options verbatim. Present exactly two choices:
+
+- **Create it now** — run the one creation path (never hand-assemble the `gh` sequence):
+
+```bash
+python3 scripts/board_bootstrap.py create --owner <owner> --repo <owner>/<repo> \
+  --title "<repo> Workflow" --seed <path of this skill folder>/board-sync.md \
+  --out docs/agents/board-sync.md
+```
+
+  It re-checks the destination and the scope before it writes anything, creates the project, the Status single-select (option names read from the seed profile's `fields.status.roles` — the board's own stage vocabulary, never a literal), and the Wave / Cluster / Spec-Path / Plan-Path fields, then discovers the real field/option IDs via `gh project field-list` and writes `docs/agents/board-sync.md` at `state=filled`, `mode=github-projects-v2` **from that readback**. Show the user `--dry-run` output first if they want to see the exact sequence. Report the created project's number and URL, and that its Status roles now resolve.
+
+- **Not now** — create nothing and take the stub path below unchanged.
+
+**A non-zero exit is a stub, never a partial claim.** The helper writes no profile when the destination is consumer-owned, the scope is missing (exit 3), or creation/readback/validation fails — so a half-created board can never produce a profile claiming fields that do not exist. On any non-zero exit, relay its message (it names the project it created, if any, so the user can finish or delete it), then take the stub path; never hand-write a `state=filled` profile and never retry creation without asking again.
+
+**Fallback (the single catch-all — declined / no board / >1 / ambiguous / scope error / read failure / creation failure):** write `board-sync.md` with `state=stub`, `mode=github-projects-v2`, and inline **instructions**: which fields the workflow profile needs (a Status single-select with your stage options; optionally a Wave number, a Cluster text, a Spec-Path / Plan-Path text), how to create the board in the GitHub UI / `gh`, and "then run `/setup-workflow` again — it will discover and fill the IDs." Retryable.
 
 **Optional — Phase field + saved Views (Program route only):** never
 auto-discovered or auto-created, unlike the fields above — a Phase field's

package/.agents/skills/setup-workflow/board-sync.md

@@ -3,8 +3,8 @@
 How the board-managed workflow skills (`to-prd`, `to-issues`, `board-to-waves`, …) address this project's GitHub-Projects board. A board stores its fields under opaque GraphQL IDs that differ per board, so they are recorded here rather than hardcoded in any skill.
 
 `/setup-workflow` writes this file in one of three states (see the sentinel on the first line):
-- **`state=filled`** — the IDs below were discovered from your board.
-- **`state=stub`** — no single board was found; fill the IDs by creating the board (below) and re-running `/setup-workflow`.
+- **`state=filled`** — the IDs below were discovered from your board (an existing one, or the one `/setup-workflow` offered to create for you).
+- **`state=stub`** — no single board was filled: you declined the creation offer, `gh` lacked the `project` scope, several boards were ambiguous, or creation failed. Create the board (below) and re-run `/setup-workflow`.
 - **`state=not-applicable`** (`mode=none`) — this project does not use a GitHub-Projects board.
 
 ## Board profile — fields the workflow skills use
@@ -106,6 +106,10 @@ their titles unchanged; set it once to match your board's language.
 
 ## If the IDs are not yet filled (stub)
 
+**Let setup create the board.** Ensure `gh` has the scopes (`gh auth refresh -s project,read:project`) and re-run `/setup-workflow`: with no board and the scope present it *offers* to create one. On your yes it runs `scripts/board_bootstrap.py`, which creates the project plus the Status single-select (its options named after the `roles` map below) and the Wave / Cluster / Spec-Path / Plan-Path fields, reads the real IDs back, and rewrites this file at `state=filled`. Nothing is created without that explicit yes, and a failed run leaves this stub in place rather than a half-true profile.
+
+**Or build it by hand:**
+
 1. Create a GitHub-Projects (v2) board for this owner and add the fields above (at minimum a `Status` single-select with your stage options — the recommended stage names are `Idea, Triaged, Spec, In Progress, Review, Done`, matching the seeded `roles` defaults).
 2. Ensure `gh` has the scopes: `gh auth refresh -s project,read:project`.
 3. Re-run `/setup-workflow` — it discovers the board (`gh project field-list`) and fills the IDs here automatically.

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

@@ -74,6 +74,40 @@ key. Consumer values are never normalized on adoption.
 Empty command surfaces are honest inactive defaults. Setup recommends concrete
 project commands from the tools already present, then asks before activating.
 
+## Profile glob dialect
+
+`baseline.sourceGlobs`, `preRefactor.surfaces[].globs`, and
+`stopChecks.surfaces[].globs` are matched by the one shared dialect in
+`scripts/profile_globs.py` — the same matcher Worktree Lifecycle uses for its
+scratch and landing-artifact policies. 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 `src/**` covers `src/a/b.ts`, `**/*.ts` covers both `index.ts` and
+`src/index.ts`, and `*.ts` covers only a root-level file.
+
+A profile written for the older whole-string matcher can therefore change
+meaning. When adopting an existing profile, or after any kit update, review it:
+
+```bash
+python3 scripts/profile_globs.py docs/agents/workflow-capabilities.json
+```
+
+The check names every pattern whose match set narrows or widens, prints the
+concrete witness path that proves the difference, and separately flags patterns
+that only matched case-insensitively on the previous matcher. 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. The check reads
+the profile and never edits it.
+
 ## Hook ownership
 
 - PreToolUse on Read:

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