@windyroad/retrospective 0.23.1-preview.583 → 0.23.1-preview.587

package/.claude-plugin/plugin.json

@@ -52,6 +52,18 @@
         },
         "schema_version": "2.0"
       },
+      "migrate-briefing": {
+        "band": "Experimental",
+        "bootstrapping": true,
+        "computed_at": "2026-06-06T00:00:00Z",
+        "evidence": {
+          "breaking_change_age_days": null,
+          "closed_tickets_window": 0,
+          "days_shipped": 0,
+          "invocations_30d": 0
+        },
+        "schema_version": "2.0"
+      },
       "run-retro": {
         "band": "Alpha",
         "computed_at": "2026-05-18T11:42:50Z",

package/README.md

@@ -50,6 +50,7 @@ The plugin also triggers a reminder via a `Stop` hook when a session ends natura
 | ------- | --------- | --- |
 | `/wr-retrospective:run-retro` | Run a session retrospective; emits the briefing update, advisory detector outputs, and the Pipeline Instability section per Step 2b | Alpha |
 | `/wr-retrospective:analyze-context` | Deep on-demand context-usage analyser per ADR-043; produces per-turn attribution and trim suggestions | Experimental |
+| `/wr-retrospective:migrate-briefing` | One-time idempotent migration of a legacy single-file `docs/BRIEFING.md` into the per-topic `docs/briefing/` tree the session-start hook + Tier-3 rotation expect (ADR-040) | Experimental |
 
 ## Advisory scripts
 

package/bin/wr-retrospective-migrate-briefing

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/migrate-briefing.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/migrate-briefing.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/retrospective",
-  "version": "0.23.1-preview.583",
+  "version": "0.23.1-preview.587",
   "description": "Session retrospectives that update briefings and create problem tickets",
   "bin": {
     "windyroad-retrospective": "./bin/install.mjs"

package/scripts/migrate-briefing.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# Migrate a legacy single-file docs/BRIEFING.md to the per-topic
+# docs/briefing/ tree expected by the wr-retrospective Tier-3 rotation
+# contract (ADR-040). Idempotent: silently no-ops when the tree already
+# exists or when no legacy file is present.
+#
+# Closes P204.
+#
+# Usage:
+#   wr-retrospective-migrate-briefing [--dry-run] [--force]
+#
+# @adr ADR-040 (session-start briefing surface — target tree shape)
+# @adr ADR-014 (governance skills commit their own work — invoked by SKILL.md)
+# @adr ADR-038 (progressive disclosure — SKILL.md + REFERENCE.md split)
+# @adr ADR-049 (plugin-bundled scripts on $PATH)
+# @problem P204 (no migrate-briefing skill — legacy → tree migration manual)
+
+set -euo pipefail
+
+DRY_RUN=0
+FORCE=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --force)   FORCE=1;   shift ;;
+    -h|--help)
+      cat <<EOF
+Usage: wr-retrospective-migrate-briefing [--dry-run] [--force]
+
+Migrate legacy docs/BRIEFING.md to docs/briefing/<topic>.md tree.
+
+Flags:
+  --dry-run   Print the planned topic slugs and file paths; no writes.
+  --force     Re-run even when docs/briefing/README.md already exists.
+EOF
+      exit 0 ;;
+    *)
+      printf 'migrate-briefing: unknown flag: %s\n' "$1" >&2
+      exit 2 ;;
+  esac
+done
+
+LEGACY="docs/BRIEFING.md"
+TREE_DIR="docs/briefing"
+TREE_INDEX="$TREE_DIR/README.md"
+
+# Idempotency: tree already present.
+if [ -f "$TREE_INDEX" ] && [ "$FORCE" != "1" ]; then
+  echo "migrate-briefing: $TREE_INDEX already exists; tree already migrated (no action)."
+  exit 0
+fi
+
+# Idempotency: no legacy file (or empty stub).
+if [ ! -s "$LEGACY" ]; then
+  echo "migrate-briefing: $LEGACY missing or empty; nothing to migrate (no action)."
+  exit 0
+fi
+
+# Slug derivation: heading text → kebab-case-truncated-to-60.
+derive_slug() {
+  printf '%s' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' \
+    | cut -c1-60
+}
+
+# Stage outputs under a temp dir so a parse failure mid-walk leaves the
+# repo untouched. Atomic-move into place after the walk completes.
+STAGING="$(mktemp -d -t migrate-briefing.XXXXXX)"
+trap 'rm -rf "$STAGING"' EXIT
+
+PREAMBLE_FILE="$STAGING/__preamble__"
+INDEX_LINES="$STAGING/__index__"
+: > "$PREAMBLE_FILE"
+: > "$INDEX_LINES"
+
+current_slug="__preamble__"
+current_file="$PREAMBLE_FILE"
+in_fence=0
+topic_index=0
+
+# Track slug → original-heading so the index row preserves human label.
+declare -A SLUG_HEADING
+declare -A SLUG_TAKEN
+
+while IFS= read -r line || [ -n "$line" ]; do
+  # Column-anchored fence toggle (``` or ~~~ at column 0).
+  if [[ "$line" =~ ^(\`\`\`|~~~) ]]; then
+    in_fence=$(( 1 - in_fence ))
+    printf '%s\n' "$line" >> "$current_file"
+    continue
+  fi
+
+  # Inside a fence: emit verbatim, never promote.
+  if [ "$in_fence" -eq 1 ]; then
+    printf '%s\n' "$line" >> "$current_file"
+    continue
+  fi
+
+  # H2 marker → close current topic, start new one.
+  if [[ "$line" =~ ^\#\#[[:space:]]+(.+)$ ]]; then
+    heading_text="${BASH_REMATCH[1]}"
+    base_slug="$(derive_slug "$heading_text")"
+    if [ -z "$base_slug" ]; then
+      topic_index=$(( topic_index + 1 ))
+      base_slug="topic-$topic_index"
+    fi
+    # Collision handling.
+    candidate="$base_slug"
+    n=2
+    while [ -n "${SLUG_TAKEN[$candidate]:-}" ]; do
+      candidate="${base_slug}-${n}"
+      n=$(( n + 1 ))
+    done
+    SLUG_TAKEN[$candidate]=1
+    SLUG_HEADING[$candidate]="$heading_text"
+    current_slug="$candidate"
+    current_file="$STAGING/${current_slug}.md"
+    : > "$current_file"
+    printf '%s\n' "$line" >> "$current_file"
+    echo "$current_slug" >> "$INDEX_LINES"
+    continue
+  fi
+
+  # Plain content → emit to current topic body.
+  printf '%s\n' "$line" >> "$current_file"
+done < "$LEGACY"
+
+# Build the README index.
+README_OUT="$STAGING/README.md"
+today="$(date +%Y-%m-%d)"
+{
+  echo "# Project Briefing"
+  echo
+  echo "Migrated from legacy \`docs/BRIEFING.md\` via \`/wr-retrospective:migrate-briefing\` on $today."
+  echo
+  echo "## Critical Points (Session-Start Surface)"
+  echo
+  echo "_To be populated by the next \`/wr-retrospective:run-retro\` Step 1.5 signal-vs-noise pass (per ADR-040)._"
+  echo
+  echo "## Topic Index"
+  echo
+  echo "| File | Source heading |"
+  echo "|---|---|"
+  while IFS= read -r slug; do
+    [ -z "$slug" ] && continue
+    heading="${SLUG_HEADING[$slug]:-$slug}"
+    echo "| [${slug}.md](./${slug}.md) | ${heading} |"
+  done < "$INDEX_LINES"
+  if [ -s "$PREAMBLE_FILE" ]; then
+    echo
+    echo "## Preamble"
+    echo
+    cat "$PREAMBLE_FILE"
+  fi
+} > "$README_OUT"
+
+# Dry-run: print the plan, do not write.
+if [ "$DRY_RUN" = "1" ]; then
+  echo "migrate-briefing: --dry-run plan:"
+  echo "  index → $TREE_INDEX"
+  while IFS= read -r slug; do
+    [ -z "$slug" ] && continue
+    echo "  topic → $TREE_DIR/${slug}.md  (heading: ${SLUG_HEADING[$slug]:-?})"
+  done < "$INDEX_LINES"
+  echo "  rename → $LEGACY → $LEGACY.migrated-$today"
+  exit 0
+fi
+
+# Atomic move into place.
+mkdir -p "$TREE_DIR"
+cp "$README_OUT" "$TREE_INDEX"
+while IFS= read -r slug; do
+  [ -z "$slug" ] && continue
+  cp "$STAGING/${slug}.md" "$TREE_DIR/${slug}.md"
+done < "$INDEX_LINES"
+
+# Retire the legacy file under a date-stamped suffix so its content is
+# preserved on disk but no longer matches the SessionStart hook's reads.
+if git -C . rev-parse HEAD >/dev/null 2>&1; then
+  git mv "$LEGACY" "${LEGACY}.migrated-${today}" 2>/dev/null \
+    || mv "$LEGACY" "${LEGACY}.migrated-${today}"
+else
+  mv "$LEGACY" "${LEGACY}.migrated-${today}"
+fi
+
+# Final report.
+echo "migrate-briefing: migrated $LEGACY → $TREE_DIR/ ($(wc -l < "$INDEX_LINES" | tr -d ' ') topic files + README index)."
+echo "migrate-briefing: legacy file retired as ${LEGACY}.migrated-${today}."

package/skills/migrate-briefing/REFERENCE.md

@@ -0,0 +1,135 @@
+# migrate-briefing — Reference
+
+Edge cases, algorithm detail, and recovery procedures for `/wr-retrospective:migrate-briefing`. SKILL.md is the canonical contract surface; this file expands the points the SKILL summary defers per ADR-038 progressive disclosure.
+
+## Heading-extraction algorithm
+
+The legacy `docs/BRIEFING.md` is walked line-by-line by `bin/migrate-briefing.sh`. The walker maintains two pieces of state:
+
+- `in_fence` — boolean, toggled when a ` ``` ` or `~~~` fence opens or closes at column 0. Lines inside a fence are emitted to the **current** topic body without heading-pattern matching.
+- `current_slug` — the active topic slug. Defaults to a special `__preamble__` slug for content before the first H2.
+
+For each input line:
+
+1. If the line is a fence delimiter at column 0, flip `in_fence` and emit verbatim.
+2. Else if `in_fence` is true, emit the line verbatim to the current topic body.
+3. Else if the line matches `^## ` (H2 marker at column 0), close the previous topic, derive a new slug from the heading text, and start a new topic body. The H2 line itself becomes the first line of the new topic body (so the heading is preserved in the per-topic file).
+4. Else emit the line verbatim to the current topic body.
+
+Output per topic:
+
+- `__preamble__` → contents (if non-empty) written into the README index under a "Preamble" section.
+- Every other slug → written to `docs/briefing/<slug>.md`.
+
+### Slug derivation
+
+```
+slug = heading_text
+  | lowercase
+  | replace non-[a-z0-9]+ runs with '-'
+  | trim leading and trailing '-'
+  | truncate to 60 chars
+```
+
+If the resulting slug is empty (e.g. an H2 with no alphanumeric content), substitute `topic-<N>` where `<N>` is the sequential topic index.
+
+### Collision handling
+
+A flat slug-set is maintained. When a derived slug collides with one already taken:
+
+```
+candidate = slug
+n = 2
+while candidate in taken:
+  candidate = slug + "-" + str(n)
+  n += 1
+slug = candidate
+```
+
+Worked example — legacy file with three `## Hooks` sections:
+
+- First section → `hooks.md`
+- Second → `hooks-2.md`
+- Third → `hooks-3.md`
+
+Collisions are surfaced in the final report so the adopter can rename for clarity.
+
+## Code-fence-awareness rationale
+
+A legacy briefing entry that documents a hook script may include a fenced bash block with `## Some heading` as a literal source line. Without fence-awareness, the walker would treat that line as a topic marker and shred the code block across two files. The fence guard preserves the example intact in whatever topic owns the surrounding prose.
+
+The guard is column-anchored (`^\\\`\\\`\\\``) — indented fences inside list items are NOT recognised as fence delimiters. This is deliberate: GFM fenced blocks inside list items use different parsing rules and rarely contain heading-pattern lines that would mislead the splitter; the simpler column-anchored detector covers >95% of real briefing content without the parser complexity of full CommonMark fence handling.
+
+## README index shape
+
+The generated `docs/briefing/README.md` has the structure:
+
+```markdown
+# Project Briefing
+
+Migrated from legacy `docs/BRIEFING.md` via `/wr-retrospective:migrate-briefing` on <YYYY-MM-DD>.
+
+## Critical Points (Session-Start Surface)
+
+_To be populated by the next `/wr-retrospective:run-retro` Step 1.5 signal-vs-noise pass (per ADR-040)._
+
+## Topic Index
+
+| File | Source heading |
+|---|---|
+| [hooks.md](./hooks.md) | Hooks |
+| [releases.md](./releases.md) | Releases |
+| ... | ... |
+
+## Preamble
+
+<contents of the legacy file before its first H2, if any>
+```
+
+The "Source heading" column is the raw H2 text from the legacy file — useful when the slug truncation or collision-suffix obscures the original meaning.
+
+## Recovery
+
+If the migration produces output the adopter is unhappy with:
+
+```bash
+git checkout HEAD -- docs/BRIEFING.md docs/briefing/
+```
+
+reverts the migration entirely. The skill commits its work as a single coherent commit per ADR-014, so revert is a single `git revert <sha>` or a checkout of the pre-skill HEAD.
+
+The legacy file is moved (not deleted) to `docs/BRIEFING.md.migrated-<date>` in the working tree before the commit, so adopters who want to inspect the original after the fact can still see it under that name in any pre-revert clone.
+
+## Scope exclusions
+
+- **Does NOT seed Critical Points**. The roll-up surface ADR-040 defines is populated from per-entry signal scores in the run-retro pass; pre-seeding from heading text would be lossy guesswork. The migrated tree's index leaves the section as a placeholder for the next retro to populate.
+- **Does NOT classify entries**. No signal-vs-noise grading happens during migration — that is run-retro Step 1.5's mechanical pass, not this skill's responsibility.
+- **Does NOT detect or split H3 subsections**. H2 is the only topic boundary. Deeper nesting stays inside the parent topic file and can be split manually if needed.
+- **Does NOT carry archives forward**. The legacy file is treated as the live current state; if it already has `## Archive` sections, they are migrated as their own topic files (named per the slug rule). No special archive-rotation handling.
+- **Does NOT touch `docs/briefing/` if a tree is already present**. The idempotency contract is hard: tree-present → no-op. Use `--force` to override.
+
+## Verification
+
+Behavioural fixture in `test/migrate-briefing-fixture.bats` exercises:
+
+- Empty repo (no legacy file) → no-op exit 0
+- Empty legacy file (`-s` returns false) → no-op exit 0
+- Tree already migrated (README.md exists) → no-op exit 0
+- Synthetic legacy file with three H2 sections → three per-topic files + index
+- Slug collision (two identical H2 texts) → `-2` suffix applied
+- Code-fence-protected H2 inside a fenced block → not promoted to topic marker
+- Idempotent re-run → no-op exit 0 (no second migration)
+
+Contract bats in `test/migrate-briefing-contract.bats` asserts:
+
+- SKILL.md frontmatter declares the skill name + description
+- ADR-032 (foreground-synchronous), ADR-014 (self-commit), ADR-038 (progressive disclosure), ADR-040 (target shape), ADR-052 (behavioural tests) all cross-referenced
+- Idempotency clause present (two-direction no-op)
+- Rule 6 audit section present (ADR-013)
+
+## Related
+
+- P204 — the ticket this skill closes
+- ADR-040 — target tree contract
+- JTBD-007 — adopter currency (pending amendment to extend scope to artefact-layout-currency per P204 new-jtbd-flag; queued for next /wr-itil:review-problems)
+- `feedback_no_repo_relative_paths_in_published_artifacts.md` — why the helper script ships via `bin/` shim per ADR-049

package/skills/migrate-briefing/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wr-retrospective:migrate-briefing
+description: Migrate a legacy single-file `docs/BRIEFING.md` into the per-topic `docs/briefing/` tree expected by the `wr-retrospective:run-retro` Tier-3 rotation and the SessionStart briefing surface. Idempotent and foreground-synchronous — silently no-ops when the tree is already in place or when no legacy file is present. Implements the migration path P204 left manual.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Migrate Briefing — Legacy Single-File → Per-Topic Tree
+
+Adopters who carried a legacy monolithic `docs/BRIEFING.md` from an older `@windyroad/retrospective` release have no automation path to the per-topic `docs/briefing/` tree the current Tier-3 rotation contract (ADR-040) expects. The dual-tolerant SessionStart hook (`packages/retrospective/hooks/session-start-briefing.sh`) keeps adopters working while the legacy file remains, but per-topic-rotation only fires once the tree exists. This skill closes the loop.
+
+See `REFERENCE.md` in this directory for the heading-extraction algorithm, slug-collision handling, code-fence-aware parsing, recovery semantics, and scope exclusions (progressive disclosure per ADR-038).
+
+## Pattern
+
+This skill is **foreground-synchronous** per [ADR-032](../../../../docs/decisions/032-governance-skill-invocation-patterns.proposed.md) (Governance skill invocation patterns). Migration writes files into `docs/briefing/` that the user normally wants to review before they commit — the wrapped subagent shape would defeat that review. The skill commits its own work per [ADR-014](../../../../docs/decisions/014-governance-skills-commit-their-own-work.proposed.md).
+
+The target tree shape (per-topic files + `README.md` index + Critical Points roll-up) is defined by [ADR-040](../../../../docs/decisions/040-session-start-briefing-surface.proposed.md). This skill is the migration path INTO that shape — not a re-encoding of it.
+
+REFERENCE.md split + the progressive-disclosure structure of this SKILL.md follows [ADR-038](../../../../docs/decisions/038-progressive-disclosure-pattern.proposed.md). Behavioural-first bats coverage follows [ADR-052](../../../../docs/decisions/052-behavioural-tests-default.proposed.md).
+
+## Idempotency Contract
+
+The skill MUST silently no-op in two cases:
+
+1. **Tree already present** — `docs/briefing/README.md` exists. Re-running after a previous migration is safe and reports "already migrated; no action".
+2. **No legacy file** — `docs/BRIEFING.md` does not exist (or is empty). Fresh adopters who never had a monolithic briefing get a "no legacy file found; no action" outcome.
+
+Both no-op paths exit 0. The fixture bats asserts both directions.
+
+## Invocation
+
+```
+/wr-retrospective:migrate-briefing [--dry-run] [--force]
+```
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Print the topic slug list + per-topic file plan; no writes. |
+| `--force` | Re-run even when `docs/briefing/README.md` already exists. Off by default — present tree is reported and skipped per the idempotency contract. |
+
+## Steps
+
+### 1. Detect inputs and short-circuit
+
+```bash
+LEGACY="docs/BRIEFING.md"
+TREE_DIR="docs/briefing"
+TREE_INDEX="$TREE_DIR/README.md"
+
+if [ -f "$TREE_INDEX" ] && [ "${FORCE:-0}" != "1" ]; then
+  echo "migrate-briefing: $TREE_INDEX already exists; tree already migrated (no action)."
+  exit 0
+fi
+
+if [ ! -s "$LEGACY" ]; then
+  echo "migrate-briefing: $LEGACY missing or empty; nothing to migrate (no action)."
+  exit 0
+fi
+```
+
+`-s` (non-empty file test) covers the empty-file edge case. An empty legacy stub is functionally indistinguishable from "no legacy file" — both warrant the no-op path.
+
+### 2. Split the legacy file by H2 headings
+
+Walk the legacy file line-by-line. Skip lines inside fenced code blocks (toggled by ` ``` ` or `~~~` at column 0) so accidental `## ` patterns inside code samples are not promoted to topic markers. Each H2 (`^## `) starts a new topic; H1 (`^# `) becomes the document preamble.
+
+Slug derivation per heading text:
+- Lowercase
+- Replace non-alphanumeric runs with `-`
+- Trim leading/trailing `-`
+- Truncate to 60 chars
+- On collision, append `-2`, `-3`, ...
+
+Write each topic body to `docs/briefing/<slug>.md`. The preamble (everything before the first H2) goes to the index README under a "Preamble" section.
+
+The full bash implementation ships as a script invoked via the `wr-retrospective-migrate-briefing` shim on `$PATH` per [ADR-049](../../../../docs/decisions/049-plugin-bundled-scripts-resolve-via-bin-on-path.proposed.md) (no repo-relative `packages/...` paths in shipped SKILL prose). The shim is wrapped per [ADR-080](../../../../docs/decisions/080-highest-version-wins-shim-wrapper-plugin-scaffold.proposed.md) so it resolves correctly under both source-monorepo execution and installed-cache execution:
+
+```bash
+wr-retrospective-migrate-briefing "$@"
+```
+
+See REFERENCE.md → "Heading-extraction algorithm" for the line-walker pseudocode + slug-collision worked example.
+
+### 3. Generate the index
+
+`docs/briefing/README.md` is written with:
+
+- Title `# Project Briefing`.
+- A short "Critical Points (Session-Start Surface)" placeholder noting the run-retro pass populates it from per-entry signal scores (ADR-040).
+- A "Topic Index" table listing every generated topic file with its source-section heading text as the human label.
+- A "Migrated from legacy `docs/BRIEFING.md` via `/wr-retrospective:migrate-briefing`" provenance line.
+
+The Critical Points section is intentionally left as a placeholder. The next `/wr-retrospective:run-retro` Step 1.5 signal-vs-noise pass populates it from per-entry classifications. Pre-seeding from heading text would be lossy guesswork.
+
+### 4. Retire the legacy file
+
+Rename `docs/BRIEFING.md` → `docs/BRIEFING.md.migrated-<date>` so the source is preserved on disk but no longer matches the SessionStart hook's read paths. `git mv` is used so the rename stages cleanly. (Per the briefing's own `git mv + Edit + git add` note — there is no Edit in this step, so no re-stage is needed.)
+
+### 5. Commit
+
+One coherent commit per ADR-014:
+
+```
+chore(retrospective): migrate legacy docs/BRIEFING.md to per-topic docs/briefing/ tree
+```
+
+with a `RISK_BYPASS: legacy-briefing-migration` trailer if the project's risk-scorer pipeline flags the bulk-file-add.
+
+## Rule 6 audit (ADR-013)
+
+This skill emits **no** `AskUserQuestion` calls. Every decision is mechanical (idempotency detection, slug derivation, file write). Per ADR-032 + ADR-013 Rule 5, mechanical / policy-authorised stages own silent classification and MUST NOT surface consent gates (P132 inverse-P078).
+
+If a future enhancement adds direction-setting choices (e.g. user-supplied topic-grouping), that surface routes through `AskUserQuestion` per ADR-013 Rule 1 with the 4-option cap. The non-interactive / AFK fallback is the queue-and-continue default per ADR-013 Rule 6 (P352 universal default) — never auto-decide direction-setters.
+
+## When to invoke
+
+- One-time during an adopter migration to `@windyroad/retrospective` ≥ the version that ships per-topic rotation.
+- After a manual edit of `docs/BRIEFING.md` that the adopter wants to formally re-split (use `--force`).
+- Safe to run any time — the idempotency contract guarantees no-op on already-migrated trees and on fresh repos.
+
+## Relationship to other skills
+
+- **Composes with** `/wr-retrospective:run-retro` — once the tree exists, Step 1.5 (signal-vs-noise pass) + Step 3 (briefing curation) operate on the per-topic files. Pre-migration, run-retro reads the legacy single file.
+- **Composes with** the SessionStart hook (`session-start-briefing.sh`) — the hook silently no-ops when neither `docs/briefing/README.md` nor `docs/BRIEFING.md` is present; this skill produces the former from the latter.
+- **Distinct from** `/install-updates` — that skill refreshes the plugin install cache; this skill migrates adopter artefacts on disk.
+
+## See also
+
+- P204 (Known Error) — the ticket this skill closes
+- ADR-040 — per-topic briefing surface contract (target shape)
+- ADR-038 — progressive disclosure pattern (SKILL/REFERENCE split)
+- ADR-052 — behavioural tests by default
+- JTBD-007 — Keep Plugins Current (adopter currency — pending amendment to extend currency scope to adopter-artefact-layout; see P204 new-jtbd-flag)

package/skills/migrate-briefing/test/migrate-briefing-contract.bats

@@ -0,0 +1,105 @@
+#!/usr/bin/env bats
+
+# Contract-level structural tests for /wr-retrospective:migrate-briefing.
+# Permitted Exception per ADR-005 — structural SKILL.md content checks,
+# mirrored on scaffold-intake-contract.bats. Behavioural coverage lives
+# in migrate-briefing-fixture.bats per ADR-052.
+#
+# Closes P204 verification surface.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_DIR="$REPO_ROOT/packages/retrospective/skills/migrate-briefing"
+  SKILL_MD="$SKILL_DIR/SKILL.md"
+  REFERENCE_MD="$SKILL_DIR/REFERENCE.md"
+  SCRIPT="$REPO_ROOT/packages/retrospective/scripts/migrate-briefing.sh"
+  SHIM="$REPO_ROOT/packages/retrospective/bin/wr-retrospective-migrate-briefing"
+}
+
+@test "migrate-briefing: SKILL.md exists" {
+  [ -f "$SKILL_MD" ]
+}
+
+@test "migrate-briefing: REFERENCE.md exists (ADR-038 split)" {
+  [ -f "$REFERENCE_MD" ]
+}
+
+@test "migrate-briefing: implementation script exists and is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+@test "migrate-briefing: bin shim exists and is executable" {
+  [ -x "$SHIM" ]
+}
+
+@test "migrate-briefing: SKILL.md frontmatter declares the skill name" {
+  run grep -F 'name: wr-retrospective:migrate-briefing' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cites ADR-040 (target tree shape — load-bearing per architect)" {
+  run grep -F 'ADR-040' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cites ADR-032 foreground-synchronous pattern" {
+  run grep -F 'ADR-032' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -iE 'foreground.synchronous' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cites ADR-014 self-commit pattern" {
+  run grep -F 'ADR-014' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cites ADR-038 progressive-disclosure pattern" {
+  run grep -F 'ADR-038' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cites ADR-052 behavioural-tests-default" {
+  run grep -F 'ADR-052' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cites ADR-049 (no repo-relative paths — recurring class)" {
+  run grep -F 'ADR-049' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md declares two-direction idempotency clause" {
+  # Both no-op directions named: tree already present + no legacy file.
+  run grep -iE 'tree.already.present|already.migrated' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -iE 'no.legacy.file|legacy.*does.not.exist|missing or empty' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md carries Rule 6 audit section (ADR-013)" {
+  run grep -F 'Rule 6' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md cross-references P204 (the closing ticket)" {
+  run grep -F 'P204' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: SKILL.md does NOT carry repo-relative packages/ paths (P151/P153/P219/P317 class)" {
+  # No bash invocations that hardcode a packages/.../scripts/ path —
+  # the script ships via ADR-049 PATH shim.
+  run grep -E 'packages/[a-z]+/scripts/migrate-briefing\.sh' "$SKILL_MD"
+  [ "$status" -ne 0 ]
+}
+
+@test "migrate-briefing: REFERENCE.md documents the heading-extraction algorithm" {
+  run grep -iE 'heading.extraction|slug.derivation|collision' "$REFERENCE_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "migrate-briefing: REFERENCE.md documents code-fence-aware parsing" {
+  run grep -iE 'fence|code.fence|in_fence' "$REFERENCE_MD"
+  [ "$status" -eq 0 ]
+}

package/skills/migrate-briefing/test/migrate-briefing-fixture.bats

@@ -0,0 +1,242 @@
+#!/usr/bin/env bats
+
+# Behavioural fixture for /wr-retrospective:migrate-briefing per ADR-052.
+# Exercises the implementation script against synthetic legacy
+# docs/BRIEFING.md fixtures in a temp dir. Asserts observable
+# file-system outcomes — per feedback_behavioural_tests.md (P081),
+# not source content.
+#
+# Closes P204 verification surface.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/retrospective/scripts/migrate-briefing.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d -t migrate-briefing-bats.XXXXXX)
+  cd "$TEST_DIR"
+  mkdir -p docs
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+# ---------------------------------------------------------------------------
+# Idempotency direction 1: no legacy file → no-op exit 0
+# ---------------------------------------------------------------------------
+
+@test "fixture: no legacy file → no-op exit 0, tree not created" {
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"nothing to migrate"* ]] || [[ "$output" == *"no action"* ]]
+  [ ! -d docs/briefing ]
+}
+
+@test "fixture: empty legacy file (zero-byte) → no-op exit 0" {
+  : > docs/BRIEFING.md
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no action"* ]]
+  [ ! -d docs/briefing ]
+}
+
+# ---------------------------------------------------------------------------
+# Idempotency direction 2: tree already present → no-op exit 0
+# ---------------------------------------------------------------------------
+
+@test "fixture: tree already present → no-op exit 0, legacy untouched" {
+  mkdir -p docs/briefing
+  cat > docs/briefing/README.md <<'EOF'
+# Project Briefing
+existing content
+EOF
+  cat > docs/BRIEFING.md <<'EOF'
+# Legacy
+## Hooks
+content
+EOF
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"already migrated"* ]]
+  [ -f docs/BRIEFING.md ]
+  run grep -F 'existing content' docs/briefing/README.md
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Core migration: synthetic legacy file with three H2 sections
+# ---------------------------------------------------------------------------
+
+@test "fixture: three-section legacy → three topic files + README index" {
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+Preamble content here.
+
+## Hooks
+
+Hook entry one.
+
+## Releases
+
+Release entry one.
+
+## Plugin Distribution
+
+Plugin distribution entry one.
+EOF
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -f docs/briefing/README.md ]
+  [ -f docs/briefing/hooks.md ]
+  [ -f docs/briefing/releases.md ]
+  [ -f docs/briefing/plugin-distribution.md ]
+  run grep -F 'Hook entry one.' docs/briefing/hooks.md
+  [ "$status" -eq 0 ]
+  run grep -F 'Release entry one.' docs/briefing/releases.md
+  [ "$status" -eq 0 ]
+  run grep -F 'Plugin distribution entry one.' docs/briefing/plugin-distribution.md
+  [ "$status" -eq 0 ]
+  run grep -F '[hooks.md](./hooks.md)' docs/briefing/README.md
+  [ "$status" -eq 0 ]
+  run grep -F 'Preamble content here.' docs/briefing/README.md
+  [ "$status" -eq 0 ]
+}
+
+@test "fixture: migration retires legacy under date-stamped suffix" {
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+## Hooks
+
+Hook content.
+EOF
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ ! -f docs/BRIEFING.md ]
+  run bash -c 'ls docs/BRIEFING.md.migrated-* 2>/dev/null'
+  [ "$status" -eq 0 ]
+  [ -n "$output" ]
+}
+
+# ---------------------------------------------------------------------------
+# Idempotent re-run after successful migration: tree present → no-op
+# ---------------------------------------------------------------------------
+
+@test "fixture: re-run after successful migration → no-op exit 0" {
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+## Hooks
+
+Hook content.
+EOF
+  bash "$SCRIPT" >/dev/null
+  # Second run sees the tree, no-ops, and does NOT re-process the
+  # already-retired legacy file.
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"already migrated"* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Slug collision: two H2 sections with the same heading text
+# ---------------------------------------------------------------------------
+
+@test "fixture: duplicate H2 headings → second slug gets -2 suffix" {
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+## Hooks
+
+First hooks section.
+
+## Hooks
+
+Second hooks section.
+EOF
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -f docs/briefing/hooks.md ]
+  [ -f docs/briefing/hooks-2.md ]
+  run grep -F 'First hooks section.' docs/briefing/hooks.md
+  [ "$status" -eq 0 ]
+  run grep -F 'Second hooks section.' docs/briefing/hooks-2.md
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Code-fence awareness: H2 inside a fenced block must NOT be promoted
+# ---------------------------------------------------------------------------
+
+@test "fixture: H2 inside fenced code block → not promoted to topic marker" {
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+## Real Topic
+
+Real content.
+
+```bash
+## This looks like H2 but is inside a fence
+echo "do not promote"
+```
+
+More real content after the fence.
+
+## Second Real Topic
+
+Second real content.
+EOF
+  run bash "$SCRIPT"
+  [ "$status" -eq 0 ]
+  # Only two topic files — the fenced ## did NOT create a third.
+  [ -f docs/briefing/real-topic.md ]
+  [ -f docs/briefing/second-real-topic.md ]
+  [ ! -f "docs/briefing/this-looks-like-h2-but-is-inside-a-fence.md" ]
+  # The fenced ## line is preserved inside real-topic.md.
+  run grep -F '## This looks like H2 but is inside a fence' docs/briefing/real-topic.md
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Dry-run: prints plan, does NOT write
+# ---------------------------------------------------------------------------
+
+@test "fixture: --dry-run prints plan and does NOT write tree" {
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+## Hooks
+
+Hook content.
+EOF
+  run bash "$SCRIPT" --dry-run
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"dry-run"* ]]
+  [[ "$output" == *"hooks"* ]]
+  [ ! -d docs/briefing ]
+  [ -f docs/BRIEFING.md ]
+}
+
+# ---------------------------------------------------------------------------
+# --force: re-runs even when tree already exists
+# ---------------------------------------------------------------------------
+
+@test "fixture: --force overrides tree-present idempotency guard" {
+  mkdir -p docs/briefing
+  echo "# stale" > docs/briefing/README.md
+  cat > docs/BRIEFING.md <<'EOF'
+# Project Briefing
+
+## Hooks
+
+Hook content.
+EOF
+  run bash "$SCRIPT" --force
+  [ "$status" -eq 0 ]
+  [ -f docs/briefing/hooks.md ]
+  run grep -F 'Migrated from legacy' docs/briefing/README.md
+  [ "$status" -eq 0 ]
+}