@windyroad/retrospective 0.23.2 → 0.24.0

package/.claude-plugin/plugin.json

@@ -78,5 +78,5 @@
     }
   },
   "name": "wr-retrospective",
-  "version": "0.23.2"
+  "version": "0.24.0"
 }

package/package.json

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

package/skills/analyze-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wr-retrospective:analyze-context
-description: Deep on-demand context-usage analyzer. Runs richer heuristics than run-retro Step 2c — per-turn attribution, per-plugin decomposition, suggestion generation, policy-breach detection. Produces a markdown report at docs/retros/<date>-context-analysis.md with an HTML-comment trailer carrying the bucket-snapshot for delta-from-prior comparison. User-invoked only; never auto-fires.
+description: Deep context-usage analyzer. Runs richer heuristics than run-retro Step 2c — per-turn attribution, per-plugin decomposition, suggestion generation, policy-breach detection. Produces a markdown report at docs/retros/<date>-context-analysis.md with an HTML-comment trailer carrying the bucket-snapshot for delta-from-prior comparison. Auto-fires from run-retro Step 2c when the combined trigger holds (calendar-elapse >14 days OR delta >20% any bucket, once-per-day guard) per ADR-043 Amendment 2026-06-08; also user-invokable on demand.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Skill
 ---
 
@@ -13,11 +13,11 @@ This skill is the **deep layer** of the two-layer design in **ADR-043** (Progres
 ## When to use
 
 - The user invokes `/wr-retrospective:analyze-context` directly.
-- The cheap layer (run-retro Step 2c) surfaced a delta anomaly (>+20% in any bucket since prior snapshot) and the user wants the per-turn / per-plugin decomposition.
+- **Auto-fired by run-retro Step 2c** when the combined trigger holds (calendar-elapse >14 days OR delta >20% any bucket since prior snapshot) and the once-per-day guard is not satisfied (no `docs/retros/<TODAY>-context-analysis.md` exists). Per ADR-043 Amendment 2026-06-08 (P295 settlement).
 - The user is preparing to trim context — e.g. before a release that introduces new hooks or skills, or after observing early compaction in long-running AFK loops.
 - The user wants a baseline snapshot at a known-good moment (e.g. immediately after a P091-cluster fix lands).
 
-**Never auto-fires.** Per ADR-043 + ADR-013 Rule 6 (AFK fallback), this skill is invoked only by explicit user direction. AFK orchestrators that observe anomalies via the cheap layer surface them in iteration summaries; the user runs this skill on return.
+**Auto-fires from run-retro Step 2c, silent in interactive and AFK modes.** Per ADR-043 Amendment 2026-06-08 + ADR-044 framework-resolution boundary, this skill auto-fires from the cheap layer when the combined trigger condition holds (calendar-elapse OR delta breach, capped at once per day). The skill never invokes `AskUserQuestion` — it writes a committed `docs/retros/<TODAY>-context-analysis.md` report and exits. AFK orchestrators read the resulting report on iteration close; the user reviews on return.
 
 ## Output Formatting
 
@@ -227,11 +227,11 @@ After the commit lands, report:
 - The number of policy breaches detected.
 - A pointer to run-retro Step 2c: *"Subsequent `/wr-retrospective:run-retro` invocations will read this report's HTML-comment trailer for delta comparison."*
 
-## Non-interactive / AFK behaviour (ADR-013 Rule 6)
+## Non-interactive / AFK behaviour (ADR-013 Rule 6 + ADR-043 Amendment 2026-06-08)
 
-This skill is **never auto-invoked** in AFK or non-interactive mode. The cheap layer (run-retro Step 2c) surfaces anomalies in the iteration summary; the user runs `/wr-retrospective:analyze-context` on return.
+This skill is **auto-invoked from run-retro Step 2c** when the combined trigger holds (calendar-elapse >14 days OR delta >20% any bucket, once-per-day guard) per ADR-043 Amendment 2026-06-08 (P295 settlement). The skill is silent (never invokes `AskUserQuestion`) and produces a committed `docs/retros/<TODAY>-context-analysis.md` report; identical behaviour in interactive and AFK modes per ADR-044 framework-resolution boundary — auto-invocation is framework-resolved mechanical action, not a user-decided surface.
 
-If invoked in a non-interactive context with `AskUserQuestion` unavailable AND the commit gate flags above-appetite risk: skip the commit, report the uncommitted report path clearly, and let the user resolve on return. The report file itself is still written — it is the evidence the user reviews.
+If invoked in a non-interactive context AND the commit gate flags above-appetite risk: skip the commit, report the uncommitted report path clearly, and let the user resolve on return. The report file itself is still written — it is the evidence the user reviews.
 
 ## Further reading (REFERENCE.md — lazy-loaded per ADR-054)
 

package/skills/analyze-context/test/analyze-context-skill-contract.bats

@@ -69,8 +69,38 @@ setup() {
   [ "$status" -eq 0 ]
 }
 
-@test "analyze-context: AFK never-auto-fires discipline declared" {
+@test "analyze-context: auto-fires from run-retro Step 2c per ADR-043 Amendment 2026-06-08 (P295)" {
+  # P295 settlement: deep layer auto-fires from cheap-layer Step 2c when the
+  # combined trigger holds. Replaces the prior 'never auto-invoked' clause.
+  run grep -iF 'auto-fires from run-retro Step 2c' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'Amendment 2026-06-08' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "analyze-context: SKILL.md no longer asserts 'never auto-invoked' / 'never auto-fires' (P295 supersedes)" {
+  # The supersession discipline: the post-P295 SKILL.md MUST NOT carry the
+  # contradicting 'never auto-fires' / 'never auto-invoked' prose, or future
+  # agents will read it as still-authoritative and revert the wiring.
   run grep -F 'never auto-invoked' "$SKILL_MD"
+  [ "$status" -ne 0 ]
+  run grep -F 'Never auto-fires' "$SKILL_MD"
+  [ "$status" -ne 0 ]
+}
+
+@test "analyze-context: cites the combined-trigger threshold values (14 days + 20%)" {
+  # ADR-043 Amendment 2026-06-08 chosen initial thresholds per ADR-026
+  # grounding rule (concrete numerics + no-prior-data sentinel).
+  run grep -F '14 days' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F '20%' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "analyze-context: cites the once-per-day guard via TODAY snapshot file presence" {
+  run grep -F 'once-per-day guard' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F '<TODAY>-context-analysis.md' "$SKILL_MD"
   [ "$status" -eq 0 ]
 }
 

package/skills/run-retro/SKILL.md

@@ -229,20 +229,31 @@ Per **ADR-043** (Progressive context-usage measurement and reporting for retrosp
    - A per-bucket table (one row per script-emitted bucket, sorted by bytes descending). Columns: `Bucket | Bytes | % of total | Δ vs prior`.
    - A top-5 offenders block when ≥ 5 buckets carry non-zero byte counts. Top-5 cites the bucket name + byte count + measurement-method (per ADR-026).
    - A one-line affordance: `Per-plugin breakdown available in /wr-retrospective:analyze-context (deep layer).`
-   - When the deep layer's last run is older than 14 days OR a bucket's delta exceeds +20% since prior snapshot, append the one-line note: `Deep analysis recommended — invoke /wr-retrospective:analyze-context.` This is a non-blocking advisory, never a prompt.
 
-4. **Forbidden phrases (ADR-026)**: the cheap-layer report MUST NOT contain qualitative-only phrases. Banned: `load is negligible`, `microseconds only`, `minimal`, `small change`, `trim X to reduce bloat` (without comparable prior). Concrete byte counts + measurement-method citations are mandatory; ungrounded fields use the explicit `not measured — <reason>` sentinel.
+4. **Auto-invoke the deep layer when the combined trigger holds (ADR-043 Amendment 2026-06-08, settles P295)**. After rendering the cheap-layer report, evaluate the combined whichever-comes-first trigger:
 
-5. **Defensive trip (fail-open)**: if the script exits non-zero or the rendered report exceeds the `THRESHOLD bytes=<N>` ceiling at runtime, skip the bucket table and emit the one-line pointer `cheap layer disabled — invoke /wr-retrospective:analyze-context for context measurement`. Log the trip in Step 2b's Pipeline Instability section so the regression is captured as a ticket candidate per the existing flow.
+   - **Calendar-elapse**: the most recent `docs/retros/*-context-analysis.md` (lex-desc sort on date in filename) is older than 14 days, OR no prior report exists.
+   - **Delta-breach**: any bucket's byte total in the just-rendered report has changed by more than 20% versus the prior snapshot (HTML-comment trailer from step 2).
+   - **Once-per-day guard**: if `docs/retros/<TODAY>-context-analysis.md` already exists (where `<TODAY>` is the current ISO date), treat the trigger as already-satisfied and skip auto-invocation. The snapshot artefact itself is the state; no new persistent state file is needed.
 
-6. **AFK behaviour (ADR-013 Rule 6)**: identical to interactive mode. The cheap layer is silent (no `AskUserQuestion`); the bucket table + advisory line ride the retro summary. AFK orchestrators read the summary on iteration close.
+   When the trigger holds AND the once-per-day guard is not satisfied, invoke `/wr-retrospective:analyze-context` via the Skill tool. The deep layer is silent (never invokes `AskUserQuestion`) and produces a committed `docs/retros/<TODAY>-context-analysis.md` report. Record the auto-invocation outcome in the cheap-layer section: `Deep analysis auto-fired — see docs/retros/<TODAY>-context-analysis.md.` Identical behaviour in interactive and AFK modes per ADR-013 Rule 6 + ADR-044 framework-resolution boundary — auto-invocation is framework-resolved mechanical action, not a user-decided surface.
+
+   When the trigger does NOT hold (no calendar elapse AND no delta breach), emit a one-line note: `Cadence trigger inactive — next auto-fire when calendar-elapse >14 days OR delta >20% any bucket.` This is non-blocking and never a prompt.
+
+   When the trigger holds but the once-per-day guard fires (today's report already exists), emit: `Cadence trigger holds; auto-fire skipped — docs/retros/<TODAY>-context-analysis.md already present.`
+
+5. **Forbidden phrases (ADR-026)**: the cheap-layer report MUST NOT contain qualitative-only phrases. Banned: `load is negligible`, `microseconds only`, `minimal`, `small change`, `trim X to reduce bloat` (without comparable prior). Concrete byte counts + measurement-method citations are mandatory; ungrounded fields use the explicit `not measured — <reason>` sentinel.
+
+6. **Defensive trip (fail-open)**: if the script exits non-zero or the rendered report exceeds the `THRESHOLD bytes=<N>` ceiling at runtime, skip the bucket table and emit the one-line pointer `cheap layer disabled — invoke /wr-retrospective:analyze-context for context measurement`. Log the trip in Step 2b's Pipeline Instability section so the regression is captured as a ticket candidate per the existing flow.
+
+7. **AFK behaviour (ADR-013 Rule 6)**: identical to interactive mode. The cheap layer is silent (no `AskUserQuestion`); the bucket table + the auto-fire / cadence-trigger line ride the retro summary. The deep layer (when auto-fired per step 4) is also silent and produces a committed report — never blocks. AFK orchestrators read the summary on iteration close.
 
 **Interaction with other surfaces:**
 
 - **`P099` Tier 3 advisory** (`check-briefing-budgets.sh`) — measures **per-topic-file** budget on `docs/briefing/<topic>.md`. The cheap layer aggregates this into a single `briefing` bucket row; the per-file detail is drillable via P099's existing surface. No double-counting.
 - **`P105` signal-vs-noise pass** (Step 1.5 of this skill) — measures **per-entry** signal scores on briefing entries. The cheap layer's `briefing` bucket is upstream of the per-entry signal scores; deep layer cites both as evidence sources.
-- **Step 4 / 4b — codification flow**: when the cheap layer surfaces a delta-from-prior anomaly that the user wants to investigate, the deep layer (`/wr-retrospective:analyze-context`) is the correct routing target — it produces a `docs/retros/<date>-context-analysis.md` report with per-turn attribution and suggestion generation. The cheap layer never auto-routes.
-- **`/wr-retrospective:analyze-context` (deep layer)** — invoked only by explicit user direction. Never auto-fires from this step. Deep-layer report writes the HTML-comment-trailer snapshot that subsequent runs of this step read.
+- **Step 4 / 4b — codification flow**: the deep layer (`/wr-retrospective:analyze-context`) produces a `docs/retros/<date>-context-analysis.md` report with per-turn attribution and suggestion generation. Per the Amendment 2026-06-08 settlement (P295), the cheap layer **auto-routes** to the deep layer when the combined trigger holds (see step 4 above) — formerly "never auto-routes" prose is superseded.
+- **`/wr-retrospective:analyze-context` (deep layer)** — auto-fires from this step (Step 2c step 4 above) when the combined trigger holds (calendar-elapse >14 days OR delta >20% any bucket, once-per-day guard) per ADR-043 Amendment 2026-06-08. Also remains user-invokable on demand. Deep-layer report writes the HTML-comment-trailer snapshot that subsequent runs of this step read.
 - **ADR-032 supersession note** (was: ADR-027 compatibility note): no Step-0 subagent migration applies — under ADR-032's foreground-synchronous pattern the script invocation runs in main-agent context as written. The migration shape this note previously discussed is obviated by the supersession.
 
 ### 2d. Ask Hygiene Pass (P135 Phase 5 / ADR-044)

package/skills/run-retro/test/run-retro-context-usage-step-2c.bats

@@ -96,3 +96,61 @@ setup() {
   [ "$step_2b_line" -lt "$step_2c_line" ]
   [ "$step_2c_line" -lt "$step_3_line" ]
 }
+
+# --- P295 (ADR-043 Amendment 2026-06-08) — auto-invoke wiring ---
+
+@test "run-retro: Step 2c cites ADR-043 Amendment 2026-06-08 and P295 settlement" {
+  run grep -F 'Amendment 2026-06-08' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'P295' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: Step 2c declares the combined whichever-comes-first trigger (calendar + delta)" {
+  run grep -F 'combined whichever-comes-first trigger' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'Calendar-elapse' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'Delta-breach' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: Step 2c declares the 14-day calendar threshold and 20% delta threshold" {
+  run grep -F 'older than 14 days' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'more than 20%' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: Step 2c declares the once-per-day guard via TODAY snapshot file presence" {
+  run grep -F 'Once-per-day guard' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F '<TODAY>-context-analysis.md' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: Step 2c auto-invokes /wr-retrospective:analyze-context via the Skill tool" {
+  run grep -F 'invoke `/wr-retrospective:analyze-context` via the Skill tool' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: Step 2c declares identical interactive + AFK auto-fire behaviour (silent deep layer)" {
+  run grep -F 'Identical behaviour in interactive and AFK modes' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'never invokes `AskUserQuestion`' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "run-retro: Step 2c no longer carries the superseded 'never auto-routes' / 'Never auto-fires' prose (P295 supersession)" {
+  # The 'never auto-routes' / 'Never auto-fires from this step' clauses were
+  # the on-demand-only design now reversed by ADR-043 Amendment 2026-06-08.
+  # The Step 2c block MUST NOT carry both the new auto-fire wiring AND the
+  # contradicting "never" prose — or future agents read it as still-canonical
+  # and revert the wiring. Bound the regex to the Step 2c block by checking
+  # the original on-demand-only sentinel phrases are absent from the whole
+  # SKILL.md (they appeared nowhere else).
+  run grep -F 'The cheap layer never auto-routes.' "$SKILL_MD"
+  [ "$status" -ne 0 ]
+  run grep -F 'Never auto-fires from this step.' "$SKILL_MD"
+  [ "$status" -ne 0 ]
+}