@ikon85/agent-workflow-kit 0.37.0 → 0.39.0

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

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

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

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

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

@@ -29,6 +29,7 @@ advisory, and safe cleanup policy as one unit.
     "operations": [
       "record-choice",
       "reconcile-profile-enabled",
+      "reconcile-landing-artifact-policy",
       "reconcile-hook-wiring"
     ]
   },
@@ -50,7 +51,8 @@ advisory, and safe cleanup policy as one unit.
     "state": "existing",
     "choice": "yes",
     "operations": [
-      "adopt-existing"
+      "adopt-existing",
+      "reconcile-landing-artifact-policy"
     ]
   },
   {
@@ -87,6 +89,50 @@ Derive its glob values from the consumer's ignored planning artefacts; an empty
 array is valid. Existing values are consumer-owned and remain byte-identical on
 adoption or rerun. Core never supplies filename defaults.
 
+Also reconcile an explicit
+`wrapup.landingGeneratedArtifactPatterns` array. Derive candidates from the
+consumer's real landing commands and ignored outputs, show the exact list for
+review, and write it only as part of that explicit setup decision. Never copy
+another repository's values or infer deletion authority from `.gitignore`
+alone. An empty array is valid. Existing configured values remain byte-identical.
+If an existing enabled profile lacks the key, report one actionable setup
+decision and leave the project layer unchanged until the consumer confirms the
+derived list.
+
+## 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

@@ -105,6 +105,52 @@ One call covers: push → PR create/reuse (+ drift markers merged into the body)
 
 STOP → diagnose in the main conversation, fix, re-run `land` (an already-merged PR resumes at teardown).
 
+Before merge, the committed worktree policy only nominates exact landing
+evidence. After merge, cleanup reloads `docs/agents/workflow-capabilities.json`
+from canonical `origin/main`; only the identical merged, attempt-bound scratch
+and generator policy authorizes each evidence path and deletion. A mismatch is
+a hard STOP that preserves every file—never bypass it with the unmerged branch
+profile.
+
+Landing provenance has one explicit relinquish route. If the STOP names an
+unfinished or drifted landing attempt and the ambiguous files cannot be restored
+to their frozen identities, run:
+
+```bash
+python3 scripts/wrapup-land.py land --branch "<branch>" --abandon-unfinished-attempt
+```
+
+This archives the started or frozen attempt receipt only. It deletes and claims
+no files, works even when the older creation baseline is missing, and returns
+before push, PR, or merge. The next `land` conservatively protects every current
+matching path; classify or move those blockers first. Do not use relinquish for
+an exact unchanged frozen attempt: a normal retry validates that evidence and
+resumes deterministically.
+
+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.