@windyroad/retrospective 0.8.0-preview.208 → 0.9.0-preview.210

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-retrospective",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Session retrospective reminders and plan review for Claude Code"
 }

package/package.json

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

package/skills/run-retro/SKILL.md

@@ -8,6 +8,21 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
 
 Reflect on the current session, update the project briefing, and create problem tickets for failures and friction.
 
+## When to use
+
+### Supported invocation surfaces
+
+- **Foreground `/wr-retrospective:run-retro`** — the canonical invocation. The user types the slash command in their parent session; the retro runs with full visibility of the session's tool-call history. This is the only invocation surface every other use case falls back to.
+- **`claude -p` subprocess invocation** — supported per **P086** (the AFK `/wr-itil:work-problems` iteration subprocess invokes run-retro before emitting `ITERATION_SUMMARY`). The subprocess has the iteration's tool-call history naturally; retro runs with iteration-bounded scope and produces correct findings for that scope. ADR-032 subprocess-boundary variant covers this surface.
+
+### Anti-pattern: Never invoke as a background agent
+
+Do **NOT** invoke run-retro via `Agent(run_in_background: true)` or any background-subagent surface (the deferred ADR-032 `capture-retro` sibling). Background subagents have isolated context at spawn — they cannot see the parent session's tool-call history, which is run-retro's primary input. A background retro would either produce empty findings, require explicit context-marshalling at spawn (the "shenanigans" the user direction rejected), or post-hoc parse session logs (out of scope today).
+
+The `/wr-retrospective:capture-retro` background sibling listed in early ADR-032 drafts is **deferred pending resolution of the context-marshalling problem** (P088, 2026-04-21 user direction: *"run-retro cannot be done as a subagent, because it won't have the context"*). The other ADR-032 background siblings (`capture-problem`, `capture-adr`) are unaffected — their inputs are self-contained aside payloads, not whole-session histories. See **ADR-032** in-scope-list amendment and **P088** ticket for the full settlement.
+
+This anti-pattern clause does NOT forbid retro inside an AFK iteration subprocess (P086) — that surface is the `claude -p` row above, not the background-agent row. Those two surfaces are distinct: `claude -p` is a fresh main Claude Code session that loads its own context naturally; `Agent(run_in_background: true)` is a subagent spawned inside an existing session whose context is isolated from the parent.
+
 ## Steps
 
 ### 1. Read the current briefing
@@ -171,6 +186,39 @@ After editing topic files, update `docs/briefing/README.md`:
 
 Use the AskUserQuestion tool to confirm any removals: "I would like to remove [item] from `docs/briefing/<topic>.md` because [reason]. Is this correct?"
 
+#### Tier 3 budget rotation pass (P099)
+
+After all topic-file edits, Step 1.5 delete-queue persistence, and the README refresh have completed, run the per-topic-file budget pass. ADR-040 Tier 3 names a 2-5 KB / topic envelope; this pass promotes that budget from informational to advisory enforcement.
+
+**Mechanism**: invoke `packages/retrospective/scripts/check-briefing-budgets.sh` (read-only diagnostic) against `docs/briefing/`. Each line of output identifies a topic file at or above the configured threshold:
+
+```
+OVER <basename> bytes=<N> threshold=<N>
+```
+
+The script's threshold defaults to `5120` bytes (the upper bound of ADR-040's Tier 3 envelope) and is overridable via `BRIEFING_TIER3_MAX_BYTES`. Empty stdout means no files are over budget — skip the rest of this pass.
+
+**Ordering**: this pass runs as the FINAL action of Step 3, after edits + Step 1.5 delete-queue persistence + README refresh. It must observe post-edit byte counts so the deletes the user confirmed in Step 1.5 are reflected in the measurement.
+
+**Interactive path (ADR-013 Rule 1)** — for each `OVER` line, invoke `AskUserQuestion`:
+
+- `header: "Rotate over-budget topic file?"`
+- `multiSelect: false`
+- The question body MUST cite the specific byte count and threshold from the script's output (per ADR-026 grounding) plus a one-line summary of what the file currently covers, so the user can pick a rotation shape without reading the full file.
+- Options (exactly four per ADR-013 Rule 1 cap):
+  1. `Split by sub-topic` — description: "Identify a coherent sub-topic in this file and migrate its entries to a new `docs/briefing/<sub-topic>.md` archive. Update README Topic Index. The agent surfaces a proposed sub-topic boundary; the user confirms in a follow-up question if needed."
+  2. `Split by date — archive oldest` — description: "Move entries older than a chosen cutoff date to a sibling archive (e.g. `docs/briefing/<topic>-archive.md`). The agent surfaces a proposed cutoff drawn from the entry HTML comment block (`first-written` field per Step 1.5)."
+  3. `Trim noise out of band` — description: "Score-and-delete in a follow-up retro is the right shape — defer rotation, leave the file as-is, and let Step 1.5's signal-vs-noise pass shrink it across cycles. Use this when no clean split boundary exists."
+  4. `Defer — record only` — description: "Surface the over-budget state in this retro's summary; take no action this session. Picks up next retro."
+
+The four options correspond to the four common rotation shapes for accumulator docs. The user's choice is recorded in the retro summary (Step 5) under the new Topic File Rotation section.
+
+**Non-interactive / AFK fallback (ADR-013 Rule 6)** — when `AskUserQuestion` is unavailable (autonomous retro, AFK orchestrator), do NOT auto-rotate. Each `OVER` line is recorded in the retro summary's "Topic File Rotation Candidates" section with the specific byte count, threshold, and one-line file summary. The user reviews on return and re-runs `/wr-retrospective:run-retro` interactively (or applies a manual split / archive) per accepted candidate. Same trust-boundary shape as Step 1.5's delete queue — surface the evidence; defer the decision.
+
+**Why advisory, not fail-closed**: the rotation is a judgment call (which sub-topic to extract, which archive shape to use). A CI-fail-on-overflow would block routine retros mid-session, directly violating JTBD-001 ("enforce governance without slowing down"). The advisory shape mirrors ADR-038's chosen response to the analogous honour-system byte-budget problem: bats catch script-contract drift; the script itself surfaces signal at runtime without halting.
+
+**Reusable pattern note** (JTBD-101): this triplet — read-only advisory script + behavioural bats fixture + ADR-tier-budget amendment — is the documented shape for any accumulator-doc surface that needs progressive-disclosure enforcement. Future surfaces (risk register per P102, ADR index, problems index) can mirror it without re-deriving.
+
 ### 4. Create or update problem tickets
 
 For each item identified in "What was harder than it should have been", "What failed", and "What should we make easier or automate", use the `/problem` skill to:
@@ -342,6 +390,14 @@ Present a summary to the user:
 |--------|----------|-----------|----------|
 | <one-line signal summary> | Hook-protocol friction / Skill-contract violations / Release-path instability / Subagent-delegation friction / Repeat-work friction / Session-wrap silent drops | <specific invocations + session-position markers + observable outcomes> | new ticket via manage-problem / appended to P<NNN> / recorded in retro only / skipped (false positive) / flagged (non-interactive) |
 
+### Topic File Rotation Candidates
+
+(Emitted only when Step 3's Tier 3 budget pass surfaced topic files at or above the configured threshold via `check-briefing-budgets.sh`. Omit this section entirely when no candidates were found — or when the interactive path resolved them all during Step 3. Populated in non-interactive / AFK mode per ADR-013 Rule 6 — the user reviews on return and applies the chosen rotation shape per candidate. P099.)
+
+| Topic file | Bytes | Threshold | Proposed rotation | Decision |
+|------------|-------|-----------|-------------------|----------|
+| `docs/briefing/<topic>.md` | <N> | <N> | split-by-subtopic / split-by-date / trim-noise / defer | applied / deferred / flagged (non-interactive) |
+
 ### Codification Candidates
 
 | Kind | Shape | Suggested name / Target file | Scope / Flaw | Triggers / Evidence | Decision |

package/skills/run-retro/test/run-retro-anti-pattern-clause.bats

@@ -0,0 +1,87 @@
+#!/usr/bin/env bats
+
+# P088: run-retro SKILL.md MUST carry a "Never invoke as a background
+# agent" anti-pattern clause that warns the agent off the
+# Agent(run_in_background: true) surface before it commits to that
+# invocation shape. The clause is the user-direction-settled outcome
+# of P088 ((b)): foreground /wr-retrospective:run-retro is the only
+# supported invocation; `claude -p` subprocess invocation (per P086)
+# remains supported because the subprocess has the iteration's context
+# naturally; background-agent invocation is deferred pending the
+# context-marshalling problem (ADR-032 capture-retro sibling, also
+# deferred).
+#
+# # Test shape: structural contract-assertion (ADR-037 fallback path)
+#
+# The architect-review verdict on P088 (2026-04-26 iter) was:
+# **structural-with-fallback-note, ship this iter**. P081 (architect-
+# design / open) flags structural grep tests on SKILL.md prose as
+# wasteful; the behavioural alternative would programmatically simulate
+# the subagent surface, invoke run-retro, and assert the skill detects
+# the surface and emits an anti-pattern denial. That requires
+# infrastructure (mock subagent stub, mock Agent-tool harness) which
+# does not exist in this repo today.
+#
+# Per ADR-037's "permitted exception" affordance for prose-only
+# contracts, this fixture takes the structural path. P081 follow-up
+# tracks the behavioural-test infrastructure build; once P081 lands a
+# subagent-surface mock, this file's structural assertions become
+# replaceable by behavioural assertions exercising the actual surface
+# detection. Until then, structural is the contract.
+#
+# # @adr ADR-037 fallback — P081 behavioural follow-up tracked.
+# # @ticket P088 — run-retro context-visibility settlement.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_MD="$REPO_ROOT/packages/retrospective/skills/run-retro/SKILL.md"
+}
+
+@test "run-retro: SKILL.md carries 'Never invoke as a background agent' anti-pattern clause (P088)" {
+  run grep -F 'Never invoke as a background agent' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: anti-pattern clause cites P088 as driver" {
+  run grep -F 'P088' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: anti-pattern clause names the supported invocation surfaces" {
+  # Foreground /wr-retrospective:run-retro — the canonical invocation.
+  run grep -F 'Foreground' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  # claude -p subprocess invocation — supported per P086 (subprocess has
+  # iteration context naturally).
+  run grep -F 'claude -p' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'P086' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: anti-pattern clause names the deferred background-agent surface explicitly" {
+  # The clause MUST mention Agent(run_in_background: true) or the
+  # capture-retro sibling so a future contributor can pattern-match
+  # the surface to the warning.
+  run grep -E 'run_in_background|capture-retro' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: anti-pattern clause appears in the preamble (before Step 1)" {
+  # The anti-pattern note belongs near the top of the SKILL so the
+  # agent encounters it before committing to an invocation surface.
+  # Placement requirement: clause appears before the '### 1. Read the
+  # current briefing' section header.
+  pos_clause=$(grep -n 'Never invoke as a background agent' "$SKILL_MD" | head -1 | cut -d: -f1)
+  pos_step1=$(grep -n '^### 1\. Read the current briefing' "$SKILL_MD" | head -1 | cut -d: -f1)
+  [ -n "$pos_clause" ]
+  [ -n "$pos_step1" ]
+  [ "$pos_clause" -lt "$pos_step1" ]
+}
+
+@test "run-retro: anti-pattern clause cross-references ADR-032 capture-retro deferral" {
+  # The clause should pin the ADR amendment so a contributor reading
+  # the SKILL can trace the deferral decision back to the ADR.
+  run grep -F 'ADR-032' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}