@windyroad/retrospective 0.25.0 → 0.26.0-preview.763

package/.claude-plugin/plugin.json

@@ -78,5 +78,5 @@
     }
   },
   "name": "wr-retrospective",
-  "version": "0.25.0"
+  "version": "0.26.0"
 }

package/hooks/hooks.json

@@ -17,6 +17,15 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start-briefing.sh"
           }
         ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/retrospective-deferral-census.sh"
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/hooks/lib/deferral-markers.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# P375 — single source of truth for the deferred-work marker vocabulary.
+#
+# A "deferred-work marker" is prose that parks work against a named-but-not-
+# self-firing re-entry point (a /skill, a lifecycle transition, "next review").
+# Per P375 the rot test is: does the trigger chain reach a SELF-FIRING event?
+# This vocabulary is what the SessionStart census (retrospective-deferral-
+# census.sh) greps for so the parked work cannot silently rot.
+#
+# Sourced, not executed. Defines DEFERRAL_MARKER_RE (grep -E, case-insensitive
+# at the call site).
+#
+# Convergence note: itil-fictional-defer-detect.sh keeps its own retro-specific
+# DEFER_RATIONALE_RE for now; folding it onto this vocabulary is a tracked P375
+# investigation task, NOT refactored cross-plugin here (ADR-002/003 plugin
+# self-containment — a retrospective lib must not become an itil runtime dep).
+# P378 fold: slice/phase-deferral phrasing ("lands in Slice N", "future slice",
+# "deferred to a hook-source slice", "<lands|deferred> ... in a future <slice|
+# pass|iter>") was MISSED by the original vocabulary — that blind spot let the
+# never-built RFC commit-trailer executor ("lands in Slice 3 task B5.T9") hide
+# from the census. Added so slice/phase-deferred-and-unbuilt work surfaces too.
+DEFERRAL_MARKER_RE='\(deferred|deferred to|pending review|re-rate at next|: deferred|lands in [Ss]lice|future slice|hook-source slice|in a future (slice|pass|iter|session)'

package/hooks/retrospective-deferral-census.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# wr-retrospective — SessionStart hook (ADR-040 class-B surface; P375)
+#
+# The "self-firing deferral census". Every session start, count deferred-work
+# markers across docs/ + packages/ (.md only) that name a re-entry point nothing
+# self-fires, and surface a bounded census so the parked work cannot silently
+# rot (P375). Clones the class-B oversight-nudge shape (architect/jtbd nudges,
+# ADR-040 session-start surface): silent-on-zero, fail-open, advisory stdout.
+#
+# .md-only scope is the code-comment false-positive guard — shipped-skill
+# deferrals live in SKILL.md, not source comments. Marker vocabulary is the
+# single source of truth in lib/deferral-markers.sh.
+#
+# AFK self-suppress: WR_SUPPRESS_DEFERRAL_CENSUS=1 (distinct from the interactive
+# oversight nudges' WR_SUPPRESS_OVERSIGHT_NUDGE — the census is advisory-stdout-
+# never-halts and is valuable under AFK, so the orchestrator suppresses it on a
+# separate axis). Only the literal "1" suppresses.
+#
+# Fail-open: never aborts session startup (ADR-013 Rule 6). Missing dirs,
+# unsourceable lib, or zero matches all exit 0 silently. ADR-040 Tier-1 budget
+# (<=2KB) honoured by capping the worst-offender list at 5 rows.
+#
+# @jtbd JTBD-001 (Enforce Governance Without Slowing Down) primary;
+#       JTBD-006 (Progress the Backlog While I'm Away) secondary.
+
+set -o pipefail
+
+[ "${WR_SUPPRESS_DEFERRAL_CENSUS:-}" = "1" ] && exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Resolve the marker vocabulary (CLAUDE_PLUGIN_ROOT in installs; dirname fallback
+# in the source monorepo / tests). Fail-open if neither resolves.
+LIB="${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/hooks/lib/deferral-markers.sh"
+[ -r "$LIB" ] || LIB="$(dirname "$0")/lib/deferral-markers.sh"
+# shellcheck source=/dev/null
+. "$LIB" 2>/dev/null || exit 0
+[ -n "${DEFERRAL_MARKER_RE:-}" ] || exit 0
+
+# Scan .md files under docs/ and packages/ only.
+SCAN_DIRS=""
+[ -d "$PROJECT_DIR/docs" ] && SCAN_DIRS="$SCAN_DIRS $PROJECT_DIR/docs"
+[ -d "$PROJECT_DIR/packages" ] && SCAN_DIRS="$SCAN_DIRS $PROJECT_DIR/packages"
+[ -n "$SCAN_DIRS" ] || exit 0
+
+# Per-file match-line counts; keep only files with >0 matches. grep no-match
+# exits 1 → `|| true` keeps the hook fail-open.
+# shellcheck disable=SC2086
+COUNTS="$(grep -rIcE --include='*.md' --exclude='CHANGELOG.md' --exclude='*-history.md' "$DEFERRAL_MARKER_RE" $SCAN_DIRS 2>/dev/null | awk -F: '$NF>0' || true)"
+[ -n "$COUNTS" ] || exit 0
+
+TOTAL=$(printf '%s\n' "$COUNTS" | awk -F: '{s+=$NF} END{print s+0}')
+FILES=$(printf '%s\n' "$COUNTS" | grep -c . 2>/dev/null || true)
+[ "${TOTAL:-0}" -gt 0 ] 2>/dev/null || exit 0
+
+# Top 5 worst offenders (bounds output to the ADR-040 Tier-1 budget).
+TOP=$(printf '%s\n' "$COUNTS" | sort -t: -k2 -nr | head -5)
+
+echo "[wr-retrospective] ${TOTAL} deferred-work marker(s) across ${FILES} file(s) name a re-entry point that nothing self-fires — they rot until someone runs a command (P375). Top offenders:"
+while IFS=: read -r f c; do
+  [ -n "$f" ] || continue
+  rel="${f#"$PROJECT_DIR"/}"
+  echo "  • ${rel}: ${c}"
+done <<< "$TOP"
+echo "  Drain: /wr-retrospective:run-retro, /wr-itil:review-problems, or work the backlog. Advisory only."
+
+exit 0

package/hooks/test/retrospective-deferral-census.bats

@@ -0,0 +1,112 @@
+#!/usr/bin/env bats
+
+# ADR-040 / P375: retrospective-deferral-census.sh (SessionStart) emits a one-line
+# census + bounded top-offenders list when deferred-work markers exist that lack a
+# self-firing trigger, is silent at zero, self-suppresses under the AFK guard
+# (WR_SUPPRESS_DEFERRAL_CENSUS=1), respects the ADR-040 Tier-1 ≤2KB budget, scans
+# BOTH docs/ and packages/ (.md only — code-comment false-positive guard), and is
+# fail-open (never aborts session startup). Behavioural — exercises the hook against
+# fixture trees. Marker vocabulary is the single source of truth in
+# lib/deferral-markers.sh (P375 "shared vocabulary").
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/retrospective/hooks/retrospective-deferral-census.sh"
+  PLUGIN_ROOT="$REPO_ROOT/packages/retrospective"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/problems" "$DIR/packages/itil/skills/foo"
+}
+
+teardown() { rm -rf "$DIR"; }
+
+mk() { mkdir -p "$(dirname "$DIR/$1")"; printf '%s\n' "$2" > "$DIR/$1"; }
+
+@test "emits a census line with the total marker count" {
+  mk "docs/problems/001-x.md" "Priority: 3 (deferred — re-rate at next /wr-itil:review-problems)"
+  mk "docs/problems/002-y.md" "**Severity**: (deferred to investigation)"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred-work marker"* ]]
+  [[ "$output" == *"[wr-retrospective]"* ]]
+}
+
+@test "lists the worst-offender files" {
+  mk "docs/problems/001-x.md" "$(printf '(deferred to A)\n(deferred to B)\n(deferred to C)')"
+  mk "docs/problems/002-y.md" "(deferred to D)"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [[ "$output" == *"001-x.md"* ]]
+}
+
+@test "scans BOTH docs/ and packages/ .md files" {
+  mk "packages/itil/skills/foo/SKILL.md" "section deferred to /wr-itil:manage-rfc accepted transition"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SKILL.md"* ]]
+}
+
+@test "silent when there are no deferred-work markers" {
+  mk "docs/problems/001-x.md" "Everything here is rated and tracked."
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "fail-open: silent + exit 0 when neither docs/ nor packages/ exists" {
+  EMPTY="$(mktemp -d)"
+  run env CLAUDE_PROJECT_DIR="$EMPTY" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  rm -rf "$EMPTY"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "fail-open: marker lib unreadable → exit 0, no output, no abort" {
+  mk "docs/problems/001-x.md" "(deferred to investigation)"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="/nonexistent/plugin/root" bash "$HOOK"
+  [ "$status" -eq 0 ]
+}
+
+@test "AFK guard WR_SUPPRESS_DEFERRAL_CENSUS=1 suppresses entirely" {
+  mk "docs/problems/001-x.md" "(deferred to investigation)"
+  run env WR_SUPPRESS_DEFERRAL_CENSUS=1 CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "guard value other than 1 does not suppress" {
+  mk "docs/problems/001-x.md" "(deferred to investigation)"
+  run env WR_SUPPRESS_DEFERRAL_CENSUS=yes CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [[ "$output" == *"deferred-work marker"* ]]
+}
+
+@test "output respects the ADR-040 Tier-1 budget (<= 2048 bytes) even with many offenders" {
+  for i in $(seq 1 50); do
+    mk "docs/problems/$(printf '%03d' "$i")-ticket.md" "$(printf '(deferred to X)\n(deferred to Y)\n(deferred to Z)')"
+  done
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  bytes=$(printf '%s' "$output" | wc -c | tr -d ' ')
+  [ "$bytes" -le 2048 ]
+}
+
+@test "excludes archival records (CHANGELOG.md, *-history.md) — they are not rotting work" {
+  mk "packages/itil/CHANGELOG.md" "$(printf '(deferred to A)\n(deferred to B)')"
+  mk "docs/problems/README-history.md" "(deferred to investigation)"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "catches slice/phase-deferral phrasing (P378 fold) — 'lands in Slice N' etc." {
+  mk "packages/itil/skills/foo/SKILL.md" "the executor lands in Slice 3 task B5.T9"
+  mk "packages/itil/skills/bar/SKILL.md" "deferred to a hook-source slice"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred-work marker"* ]]
+  [[ "$output" == *"SKILL.md"* ]]
+}
+
+@test "points at a drain path (run-retro / backlog) and cites P375" {
+  mk "docs/problems/001-x.md" "(deferred to investigation)"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [[ "$output" == *"P375"* ]]
+}

package/lib/install-utils.mjs

@@ -7,10 +7,12 @@ import { execSync } from "node:child_process";
 
 const MARKETPLACE_REPO = "windyroad/agent-plugins";
 const MARKETPLACE_NAME = "windyroad";
+const CODEX_MARKETPLACE_PATH = ".";
+const CODEX_MARKETPLACE_NAME = "windyroad-local";
 
 let _dryRun = false;
 
-export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+export { MARKETPLACE_REPO, MARKETPLACE_NAME, CODEX_MARKETPLACE_PATH, CODEX_MARKETPLACE_NAME };
 
 export function setDryRun(value) {
   _dryRun = value;
@@ -35,16 +37,34 @@ export function run(cmd, label) {
   }
 }
 
-export function checkPrerequisites() {
+function runtimesFor(runtime = "claude") {
+  if (runtime === "both") return ["claude", "codex"];
+  return [runtime];
+}
+
+export function checkPrerequisites({ runtime = "claude" } = {}) {
   if (_dryRun) return;
 
-  try {
-    execSync("claude --version", { stdio: "pipe" });
-  } catch {
-    console.error(
-      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
-    );
-    process.exit(1);
+  for (const currentRuntime of runtimesFor(runtime)) {
+    if (currentRuntime === "claude") {
+      try {
+        execSync("claude --version", { stdio: "pipe" });
+      } catch {
+        console.error(
+          "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+        );
+        process.exit(1);
+      }
+    } else if (currentRuntime === "codex") {
+      try {
+        execSync("codex --version", { stdio: "pipe" });
+      } catch {
+        console.error(
+          "Error: 'codex' CLI not found. Install Codex CLI first:\n  https://developers.openai.com/codex\n"
+        );
+        process.exit(1);
+      }
+    }
   }
 }
 
@@ -55,6 +75,13 @@ export function addMarketplace() {
   );
 }
 
+export function addCodexMarketplace() {
+  return run(
+    `codex plugin marketplace add ${CODEX_MARKETPLACE_PATH}`,
+    `Codex marketplace: ${CODEX_MARKETPLACE_NAME}`
+  );
+}
+
 export function installPlugin(pluginName, { scope = "project" } = {}) {
   return run(
     `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
@@ -62,6 +89,13 @@ export function installPlugin(pluginName, { scope = "project" } = {}) {
   );
 }
 
+export function installCodexPlugin(pluginName) {
+  return run(
+    `codex plugin add ${pluginName}@${CODEX_MARKETPLACE_NAME}`,
+    pluginName
+  );
+}
+
 export function updatePlugin(pluginName, { scope = "project" } = {}) {
   return run(
     `claude plugin update "${pluginName}@${MARKETPLACE_NAME}" --scope ${scope}`,
@@ -69,18 +103,36 @@ export function updatePlugin(pluginName, { scope = "project" } = {}) {
   );
 }
 
+export function updateCodexMarketplace() {
+  return run(
+    `codex plugin marketplace add ${CODEX_MARKETPLACE_PATH}`,
+    `Codex marketplace: ${CODEX_MARKETPLACE_NAME}`
+  );
+}
+
 export function uninstallPlugin(pluginName) {
   return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
 }
 
+export function uninstallCodexPlugin(pluginName) {
+  return run(`codex plugin remove ${pluginName}`, `Removing ${pluginName}`);
+}
+
 /**
  * Install a single package: marketplace add + plugin install.
  */
-export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+export function installPackage(pluginName, { deps = [], scope = "project", runtime = "claude" } = {}) {
   console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
 
-  addMarketplace();
-  installPlugin(pluginName, { scope });
+  if (runtime === "claude" || runtime === "both") {
+    addMarketplace();
+    installPlugin(pluginName, { scope });
+  }
+
+  if (runtime === "codex" || runtime === "both") {
+    addCodexMarketplace();
+    installCodexPlugin(pluginName);
+  }
 
   if (deps.length > 0) {
     console.log(`\nNote: This plugin works best with:`);
@@ -90,34 +142,47 @@ export function installPackage(pluginName, { deps = [], scope = "project" } = {}
   }
 
   console.log(
-    `\nDone! Restart Claude Code to activate.\n`
+    `\nDone! Restart ${runtime === "codex" ? "Codex" : runtime === "both" ? "Claude Code and Codex" : "Claude Code"} to activate.\n`
   );
 }
 
 /**
  * Update a single package.
  */
-export function updatePackage(pluginName, { scope = "project" } = {}) {
+export function updatePackage(pluginName, { scope = "project", runtime = "claude" } = {}) {
   console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
 
-  run(
-    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
-    "Updating marketplace"
-  );
-  updatePlugin(pluginName, { scope });
+  if (runtime === "claude" || runtime === "both") {
+    run(
+      `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+      "Updating marketplace"
+    );
+    updatePlugin(pluginName, { scope });
+  }
 
-  console.log("\nDone! Restart Claude Code to apply updates.\n");
+  if (runtime === "codex" || runtime === "both") {
+    updateCodexMarketplace();
+    installCodexPlugin(pluginName);
+  }
+
+  console.log(`\nDone! Restart ${runtime === "codex" ? "Codex" : runtime === "both" ? "Claude Code and Codex" : "Claude Code"} to apply updates.\n`);
 }
 
 /**
  * Uninstall a single package.
  */
-export function uninstallPackage(pluginName) {
+export function uninstallPackage(pluginName, { runtime = "claude" } = {}) {
   console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
 
-  uninstallPlugin(pluginName);
+  if (runtime === "claude" || runtime === "both") {
+    uninstallPlugin(pluginName);
+  }
+
+  if (runtime === "codex" || runtime === "both") {
+    uninstallCodexPlugin(pluginName);
+  }
 
-  console.log("\nDone. Restart Claude Code to apply changes.\n");
+  console.log(`\nDone. Restart ${runtime === "codex" ? "Codex" : runtime === "both" ? "Claude Code and Codex" : "Claude Code"} to apply changes.\n`);
 }
 
 /**
@@ -131,6 +196,7 @@ export function parseStandardArgs(argv) {
     update: args.includes("--update"),
     dryRun: args.includes("--dry-run"),
     scope: "project",
+    runtime: "claude",
   };
   const scopeIdx = args.indexOf("--scope");
   if (scopeIdx !== -1 && args[scopeIdx + 1]) {
@@ -142,5 +208,15 @@ export function parseStandardArgs(argv) {
       process.exit(1);
     }
   }
+  const runtimeIdx = args.indexOf("--runtime");
+  if (runtimeIdx !== -1 && args[runtimeIdx + 1]) {
+    const val = args[runtimeIdx + 1];
+    if (["claude", "codex", "both"].includes(val)) {
+      flags.runtime = val;
+    } else {
+      console.error("--runtime requires: claude, codex, or both");
+      process.exit(1);
+    }
+  }
   return flags;
 }

package/package.json

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