@windyroad/retrospective 0.15.0 → 0.16.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -32,17 +32,58 @@ Restart Claude Code after installing.
 /wr-retrospective:run-retro
 ```
 
-This walks through the session's work, identifies what went well and what didn't, updates `docs/BRIEFING.md`, and creates problem tickets for any failures.
+This walks through the session's work, identifies what went well and what didn't, updates `docs/BRIEFING.md`, and creates problem tickets for any failures. The retro also runs every shipped advisory script (briefing budgets, ask-hygiene, README JTBD currency per ADR-051, SKILL.md runtime budgets per ADR-054) so doc-content drift surfaces in the retro summary alongside session-level reflections.
+
+**Analyse session context usage:**
+
+```
+/wr-retrospective:analyze-context
+```
+
+Deep on-demand context-usage analyser per ADR-043. Generates per-source attribution, per-plugin decomposition, and suggested trim actions. Complements the cheap-layer measurement that `run-retro` always emits.
 
 The plugin also triggers a reminder via a `Stop` hook when a session ends naturally.
 
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/wr-retrospective:run-retro` | Run a session retrospective; emits the briefing update, advisory detector outputs, and the Pipeline Instability section per Step 2b |
+| `/wr-retrospective:analyze-context` | Deep on-demand context-usage analyser per ADR-043; produces per-turn attribution and trim suggestions |
+
+## Advisory scripts
+
+Each script ships as a `bin/`-resolvable shim per ADR-049. They emit signal-as-data on stdout and exit 0 always (advisory per ADR-013 Rule 6). `run-retro` invokes them as part of Step 2b / Step 3 and surfaces their findings in the retro summary; they can also be invoked manually before a release or audit.
+
+| Shim | Purpose |
+|------|---------|
+| `wr-retrospective-check-readme-jtbd-currency` | ADR-051 Phase 1 detector — surfaces drift between plugin READMEs and the JTBD jobs they cite |
+| `wr-retrospective-check-skill-md-budgets` | ADR-054 detector — flags SKILL.md files over the WARN / MUST_SPLIT byte budget |
+| `wr-retrospective-check-internal-id-leaks` | ADR-055 detector — flags internal IDs leaking into published artefacts |
+| `wr-retrospective-list-plugin-attribution` | Per-plugin context attribution support for `analyze-context` |
+| `wr-retrospective-measure-context-budget` | Cheap-layer context-budget measurement support for `run-retro` Step 2c |
+
 ## How It Works
 
 | Hook | Trigger | What it does |
 |------|---------|-------------|
-| `check-deps.sh` | Session start | Verifies that `wr-itil` and `wr-risk-scorer` are installed |
+| `bin/check-deps.sh` | Session start | Verifies that `wr-itil` and `wr-risk-scorer` are installed |
+| `session-start-briefing.sh` | Session start | Surfaces the latest `docs/BRIEFING.md` and any pending retrospective items so the new session begins with prior-session context (per [ADR-040](../../docs/decisions/040-session-start-briefing-surface.proposed.md)) |
 | `retrospective-reminder.sh` | Session end | Reminds you to run a retrospective |
 
+## Jobs to be Done
+
+This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](../../docs/decisions/051-jtbd-anchored-readme-with-drift-advisory.proposed.md), the persona-grouped JTBD anchor is the canonical source of truth for the README's value framing.
+
+### Solo developer
+
+- **[JTBD-006 Progress the Backlog While I'm Away](../../docs/jtbd/solo-developer/JTBD-006-work-backlog-afk.proposed.md)** — every AFK iteration runs a retrospective before exiting so per-iter friction is captured as problem tickets and surfaced on return; learnings flow back into `docs/BRIEFING.md` so the next session starts with context.
+- **[JTBD-002 Ship AI-Assisted Code with Confidence](../../docs/jtbd/solo-developer/JTBD-002-ship-with-confidence.proposed.md)** — release-readiness signals (pipeline-instability scan, ask-hygiene check, doc-currency advisory) accumulate at retro time so unresolved friction is visible before the next release.
+
+### Plugin user
+
+- **[JTBD-302 Trust That the README Describes the Plugin I Just Installed](../../docs/jtbd/plugin-user/JTBD-302-trust-readme-describes-installed-behaviour.proposed.md)** — this README is anchored on current JTBD job IDs; drift between prose and shipped behaviour is detectable at retro time per ADR-051.
+
 ## Updating and Uninstalling
 
 ```bash

package/package.json

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

package/skills/run-retro/SKILL.md

@@ -159,6 +159,23 @@ The shape mirrors P068's Step 4a Verification-close housekeeping: glob / evidenc
 
 6. **Non-interactive / AFK fallback (ADR-013 Rule 6)**: when `AskUserQuestion` is unavailable (autonomous retro, batch session-wrap), do NOT auto-create tickets — record each detection in the retro summary's new **Pipeline Instability** section with its category, citations, and dedup status (`new` or `matches P<NNN>`). The user reviews on return and runs `/wr-itil:manage-problem` per accepted detection. Same trust-boundary shape as Step 4a's AFK deferral: surface the evidence, defer the decision. This matches the user's documented preference (feedback_verify_from_own_observation.md memory): surface observations from the agent's own in-session activity, but ticket-creation decisions remain user-confirmed.
 
+**JTBD currency advisory (ADR-051 Phase 1, P158).** Beyond the categorical pipeline-instability detection above, Step 2b also runs the ADR-051 Phase 1 advisory detector on every retro to surface README-content drift between the suite's plugin READMEs and the documented JTBD jobs they cite. Drift here is not pipeline-instability in the conventional sense — it is content-currency — but the surfacing channel is the same: the retro summary's Pipeline Instability section. Wiring deferred from the original ADR-051 landing per Confirmation criterion 5 ("wiring into `/wr-retrospective:run-retro` Step 2b is deferred to a follow-on iter once the detector is empirically validated against current READMEs"); the empirical-validation precondition was met by commit `8df1692` (the retroactive refresh of 12 plugin READMEs to JTBD-anchored shape; detector now reports `drift_instances=1`).
+
+**Mechanism**: invoke `wr-retrospective-check-readme-jtbd-currency` (resolves on `$PATH` to `packages/retrospective/scripts/check-readme-jtbd-currency.sh` per ADR-049 naming grammar). The script walks `packages/*/README.md`, greps each for `JTBD-\d{3}` citations, resolves cited IDs against `docs/jtbd/<persona>/JTBD-NNN-*.md` (any status suffix), and emits:
+
+- Per-package: `README package=<name> has_jtbd_anchor=<yes|no> cited_jobs=<N> known_jobs=<M> drift_hints=<csv>`
+- Trailing summary: `TOTAL packages=<N> with_jtbd=<M> drift_instances=<K>`
+
+Drift-hint vocabulary: `missing-jtbd-section`, `stale-jtbd-citation`, `deprecated-jtbd-citation`, `skill-inventory-drift`. Always exits 0 — the script is advisory per ADR-013 Rule 6 / ADR-040 declarative-first / ADR-051 Phase 1.
+
+**Interpretation**:
+
+1. **`drift_instances == 0`** — emit a one-line `JTBD currency advisory: clean (<N> packages)` to the retro summary's Pipeline Instability section.
+2. **`drift_instances ≥ 1`** — emit the detector's full per-package output as a fenced code block in the Pipeline Instability section. Each affected package's `drift_hints` enumerate the specific findings. Per ADR-013 Rule 6, the user reviews on return and tickets via `/wr-itil:manage-problem` per accepted finding (same trust-boundary shape as the categorical detection above — surface the evidence; defer the ticket-creation decision).
+3. **Detector failure** — if the detector exits non-zero (parse error, missing `packages/` or `docs/jtbd/` directories, runtime exception), log the failure inline as `JTBD currency advisory failed: <stderr>` but do NOT halt the retro. Same fail-open contract as Step 3's `check-briefing-budgets.sh` defensive trip — the cheap layer trips silently and degrades to a one-line pointer rather than blocking the retro.
+
+**Phase 2 escalation criterion (per ADR-051)**: if the detector emits `drift_instances ≥ 2` across 3 consecutive `chore: version packages` releases without correction, escalate to a load-bearing hook per ADR-013 Rule 6 escalation pattern. Phase 2 is out of scope for this wiring; the criterion is captured here so future contributors know the bar.
+
 **Interaction with other surfaces:**
 
 - **Step 4a (Verification-close housekeeping, P068)** — same evidence-scan shape applied to a different surface. Both share the glob / scan / categorise / specific-citation / interactive-or-AFK pattern. Step 4a scans for successful exercise of `.verifying.md` fixes; Step 2b scans for tool-level friction. They fire independently and produce independent retro-summary sections.