@windyroad/jtbd 0.14.0 → 0.14.1

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.14.0"
+  "version": "0.14.1"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wr-jtbd",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Jobs-to-be-done governance for product changes",
   "author": {
     "name": "Windy Road Technology",

package/hooks/jtbd-slide-marker.sh

@@ -2,9 +2,9 @@
 # JTBD - PostToolUse:Agent|Bash|Skill slide-marker hook (P111 + P213).
 # Slides the parent session's existing jtbd-reviewed marker forward on
 # subprocess return, treating subprocess wall-clock as continuous parent-
-# session work for TTL purposes. Only TOUCHES an existing marker — never
-# creates one (creation requires a real JTBD review parsed from the agent's
-# verdict file in jtbd-mark-reviewed.sh).
+# session work for TTL purposes. It only TOUCHES existing JTBD-review markers.
+# P368 also lets an exact successful oversight-helper event create its separate
+# document-and-session evidence marker.
 #
 # See ADR-009 "Subprocess-boundary refresh" and P111 for context. Failed
 # subprocesses (tool_response.is_error=true) do NOT extend the trust window
@@ -16,6 +16,50 @@ source "$SCRIPT_DIR/lib/gate-helpers.sh"
 _parse_input
 
 SESSION_ID=$(_get_session_id)
+
+# P368: bind oversight evidence to the exact successful Bash event rather
+# than guessing from the set of recently announced sessions.
+OVERSIGHT_PATH=$(printf '%s' "$_HOOK_INPUT" | python3 -c '
+import json, shlex, sys
+try:
+    data = json.load(sys.stdin)
+    response = data.get("tool_response", {})
+    argv = shlex.split(data.get("tool_input", {}).get("command", ""))
+    if (data.get("tool_name") == "Bash"
+            and isinstance(response, dict)
+            and response.get("is_error") is not True
+            and len(argv) == 2
+            and argv[0] == "wr-jtbd-mark-oversight-confirmed"):
+        print(argv[1])
+except Exception:
+    pass
+' 2>/dev/null)
+
+if [ -n "$OVERSIGHT_PATH" ]; then
+  if [ -z "$SESSION_ID" ]; then
+    echo "wr-jtbd-mark-oversight-confirmed: missing session id; no oversight marker written" >&2
+  else
+    ABS_DIR="$(cd "$(dirname "$OVERSIGHT_PATH")" 2>/dev/null && pwd)" || ABS_DIR=""
+    ABS_PATH="${ABS_DIR:+$ABS_DIR/}$(basename "$OVERSIGHT_PATH")"
+    case "$ABS_PATH" in
+      */docs/jtbd/*.md|*/docs/jtbd/*/*.md)
+        if command -v sha256sum >/dev/null 2>&1; then
+          PATH_HASH=$(printf '%s' "$ABS_PATH" | sha256sum | cut -d' ' -f1 | cut -c1-16)
+        elif command -v shasum >/dev/null 2>&1; then
+          PATH_HASH=$(printf '%s' "$ABS_PATH" | shasum -a 256 | cut -d' ' -f1 | cut -c1-16)
+        else
+          echo "wr-jtbd-mark-oversight-confirmed: no SHA-256 utility; no oversight marker written" >&2
+          PATH_HASH=""
+        fi
+        if [ -n "$PATH_HASH" ] && ! : > "${SESSION_MARKER_DIR:-/tmp}/oversight-confirmed-${PATH_HASH}-${SESSION_ID}"; then
+          echo "wr-jtbd-mark-oversight-confirmed: marker write failed" >&2
+        fi
+        ;;
+      *) echo "wr-jtbd-mark-oversight-confirmed: invalid JTBD path; no oversight marker written" >&2 ;;
+    esac
+  fi
+fi
+
 [ -n "$SESSION_ID" ] || exit 0
 
 slide_marker_on_subprocess_return "/tmp/jtbd-reviewed-${SESSION_ID}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"
@@ -34,6 +34,7 @@
     ".agents/",
     ".codex-plugin/",
     "lib/",
+    "!skills/*/eval/",
     "!agents/eval/",
     "!agents/test/",
     "!hooks/test/",

package/scripts/mark-oversight-confirmed.sh

@@ -3,11 +3,10 @@
 # user-substance-confirmed (P348 / ADR-110).
 #
 # JTBD-side sibling of packages/architect/scripts/mark-oversight-confirmed.sh.
-# Companion to jtbd-oversight-marker-discipline.sh (also P348). SKILLs invoke
-# this script AFTER an AskUserQuestion lands the user's substance-confirm
-# answer for a specific job or persona; the script writes the evidence marker
-# that the hook reads to permit the subsequent Edit/Write that introduces
-# `human-oversight: confirmed` into that artefact's frontmatter.
+# Companion to jtbd-oversight-marker-discipline.sh. SKILLs invoke this as a
+# standalone Bash command AFTER an AskUserQuestion lands the user's substance-
+# confirm answer. The existing PostToolUse:Bash hook binds that exact command
+# event's path and session id into the marker.
 #
 # Why the marker is required:
 #   ADR-068 mirrors ADR-066's `human-oversight: confirmed` marker contract on
@@ -23,100 +22,25 @@
 # ADR-110), which the drain
 # (/wr-jtbd:confirm-jobs-and-personas) later promotes.
 #
-# Marker convention:
-#   /tmp/oversight-confirmed-<sha256-of-path>-<session-id>
-#   Shared marker namespace with the architect hook — both hooks consume the
-#   same marker file shape. Written under EVERY recent candidate session SID
-#   per ADR-050 Option C.
-#
 # Usage:
 #   wr-jtbd-mark-oversight-confirmed <artefact-path>
-#     <artefact-path> — the JTBD or persona file path the user just
-#                       substance-confirmed.
+#     Must be the whole Bash command, with exactly one JTBD/persona path.
 #
 # Exit codes:
-#   0 — marker(s) written for at least one candidate SID, OR no candidate
-#       SID was discoverable (cold path: no announce markers yet). The latter
-#       writes no marker and prints a loud stderr diagnostic (P368) explaining
-#       the downstream hook deny, then exits 0 so SKILL flows do not crash
-#       before any hook has fired in the session.
-#   2 — bad argument (missing or empty artefact-path).
+#   0 — command validated; PostToolUse writes the exact-session marker.
+#   2 — bad argument count.
 #
 # @adr ADR-068 (JTBD/persona human-oversight marker)
 # @adr ADR-049 (PATH shim grammar)
-# @adr ADR-050 (multi-SID candidate enumeration)
 # @adr ADR-013 (Rule 6 fail-safe-defer in non-interactive contexts)
 # @problem P348 (iter subprocesses set human-oversight: confirmed without user event)
+# @problem P368 (candidate enumeration grants unrelated sessions)
 
 set -uo pipefail
 
-ARTEFACT_PATH="${1:-}"
-
-if [ -z "$ARTEFACT_PATH" ]; then
-  echo "wr-jtbd-mark-oversight-confirmed: missing <artefact-path>" >&2
-  exit 2
-fi
-
-# Normalize to absolute path so the hash is stable regardless of CWD.
-abs_dir="$(cd "$(dirname "$ARTEFACT_PATH")" 2>/dev/null && pwd)" || abs_dir=""
-if [ -n "$abs_dir" ]; then
-  ABS_PATH="$abs_dir/$(basename "$ARTEFACT_PATH")"
-else
-  ABS_PATH="$ARTEFACT_PATH"
-fi
-
-# Path hash — sha256, first 16 hex chars. Portable across macOS (shasum) and
-# Linux (sha256sum / shasum).
-if command -v sha256sum >/dev/null 2>&1; then
-  PATH_HASH=$(printf '%s' "$ABS_PATH" | sha256sum | cut -d' ' -f1 | cut -c1-16)
-elif command -v shasum >/dev/null 2>&1; then
-  PATH_HASH=$(printf '%s' "$ABS_PATH" | shasum -a 256 | cut -d' ' -f1 | cut -c1-16)
-else
-  echo "wr-jtbd-mark-oversight-confirmed: no sha256 tool available" >&2
+if [ "$#" -ne 1 ] || [ -z "$1" ]; then
+  echo "wr-jtbd-mark-oversight-confirmed: expected exactly one <artefact-path>" >&2
   exit 2
 fi
 
-MARKER_DIR="${SESSION_MARKER_DIR:-/tmp}"
-WINDOW_MINS="${SESSION_CANDIDATE_WINDOW_MINS:-1440}"
-
-# Candidate SID enumeration — recent announce markers across all systems
-# within the mtime window. Inlined for plugin self-containment (no cross-
-# plugin lib source — jtbd must not depend on architect-internal helpers
-# per ADR-002 plugin packaging).
-candidates=$(
-  {
-    if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
-      echo "$CLAUDE_SESSION_ID"
-    fi
-    # `-L` follows the start-point symlink — on macOS MARKER_DIR defaults to /tmp,
-    # a symlink to /private/tmp, which `find` would otherwise refuse to descend
-    # (no-op on Linux where /tmp is a real dir). P380.
-    find -L "$MARKER_DIR" -maxdepth 1 -name '*-announced-*' -mmin "-${WINDOW_MINS}" 2>/dev/null \
-      | sed 's|.*/||; s/.*-announced-//'
-  } | awk 'NF && !seen[$0]++'
-)
-
-# No candidate SID — cold path. Emit a loud stderr diagnostic (P368) and still
-# exit 0. Exit 0 preserves the documented contract (do not crash SKILL flows
-# before any announce marker has fired this session); the diagnostic replaces the
-# prior SILENT no-op, which masqueraded as success and left the caller to hit the
-# oversight-marker-discipline hook's deny with no idea why — the confusing loop
-# P368 documents (the deny points back at this shim, which the caller already ran).
-if [ -z "$candidates" ]; then
-  {
-    echo "wr-jtbd-mark-oversight-confirmed: no candidate session id discoverable"
-    echo "  (CLAUDE_SESSION_ID empty and no *-announced-* markers in ${MARKER_DIR} within ${WINDOW_MINS}min)."
-    echo "  NO oversight marker was written for: ${ABS_PATH}"
-    echo "  The oversight-marker-discipline hook will DENY the 'human-oversight: confirmed' Edit"
-    echo "  until a session announce marker exists. Start a fresh session, or point SESSION_MARKER_DIR"
-    echo "  at a dir containing a *-announced-<sid> file, then re-run this shim (P368)."
-  } >&2
-  exit 0
-fi
-
-while IFS= read -r sid; do
-  [ -n "$sid" ] || continue
-  : > "$MARKER_DIR/oversight-confirmed-${PATH_HASH}-${sid}"
-done <<< "$candidates"
-
 exit 0

package/skills/confirm-jobs-and-personas/SKILL.md

@@ -63,7 +63,7 @@ This is a genuine human-decision surface (the point of P288/ADR-068) — `reques
 
 ### Step 4: Apply the outcome
 
-- **Confirm / Amend**: write `human-oversight: confirmed` + `oversight-date: <today, YYYY-MM-DD>` into the file's frontmatter (insert after the `status:`/`date-created:` line if absent; never duplicate). For Amend, apply the directed change first. Edits go through the standard JTBD / architect edit gate per ADR-014.
+- **Confirm / Amend**: for Amend, apply the directed change first. Then run `wr-jtbd-mark-oversight-confirmed <job-or-persona-path>` as a standalone Bash command; do not combine it with another command, because its PostToolUse event binds the evidence to this exact session and file. Finally, write `human-oversight: confirmed` + `oversight-date: <today, YYYY-MM-DD>` into the file's frontmatter (insert after the `status:`/`date-created:` line if absent; never duplicate). Edits go through the standard JTBD / architect edit gate per ADR-014.
 - **Reject** (ADR-068 amendment per P316, mirroring ADR-066):
   1. Capture the supersede ticket via a follow-up `request_user_input`: "Which problem ticket tracks the rework?" — options: existing `P<NNN>` IDs surfaced from `docs/problems/`, **Capture a new ticket** (delegate to `/wr-itil:capture-problem`), or **Defer (leave un-tracked for now)**.
   2. If a ticket ID is captured, write `human-oversight: rejected-pending-supersede` + `supersede-ticket: P<NNN>` into the file's frontmatter. The detector excludes artifacts carrying both, so the drain stops re-asking until either the rework lands (file renamed to `*.superseded.md`) or the rejection is revisited.

package/skills/update-guide/SKILL.md

@@ -103,12 +103,14 @@ Use request_user_input to present the drafted personas and ask:
 wr-jtbd-mark-oversight-confirmed docs/jtbd/<persona-name>/persona.md
 ```
 
+Run that helper as the complete standalone Bash command. Do not combine it with another command: the PostToolUse hook binds this exact successful command event's session id and persona path into the evidence marker.
+
 ```yaml
 human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
-The `wr-jtbd-mark-oversight-confirmed` call writes the session-scoped evidence marker (`/tmp/oversight-confirmed-<sha>-<sid>`) that the `jtbd-oversight-marker-discipline.sh` PreToolUse hook reads to authorise the subsequent Edit/Write — without the helper call, the hook will DENY the marker write. This is the load-bearing born-confirmed gate: a persona authored through update-guide enters the world human-oversighted ONLY because the helper above paired the user's substance-confirm answer to the marker write. Do NOT write the marker for a persona the user has not confirmed. AFK iter subprocesses spawned via `native Codex subagent` have no `request_user_input` access; they MUST write `human-oversight: unconfirmed` (the AFK fallback enum value codified in ADR-110), which the drain (`/wr-jtbd:confirm-jobs-and-personas`) later promotes interactively. The marker is orthogonal to status.
+The helper's PostToolUse event writes the session-scoped evidence marker (`/tmp/oversight-confirmed-<sha>-<sid>`) that the `jtbd-oversight-marker-discipline.sh` PreToolUse hook reads to authorise the subsequent Edit/Write — without the helper call, the hook will DENY the marker write. This is the load-bearing born-confirmed gate: a persona authored through update-guide enters the world human-oversighted ONLY because the helper above paired the user's substance-confirm answer to the marker write. Do NOT write the marker for a persona the user has not confirmed. AFK iter subprocesses spawned via `native Codex subagent` have no `request_user_input` access; they MUST write `human-oversight: unconfirmed` (the AFK fallback enum value codified in ADR-110), which the drain (`/wr-jtbd:confirm-jobs-and-personas`) later promotes interactively. The marker is orthogonal to status.
 
 ### 5. Draft jobs
 
@@ -162,12 +164,14 @@ Use request_user_input to present the drafted jobs and ask:
 wr-jtbd-mark-oversight-confirmed docs/jtbd/<persona-name>/JTBD-NNN-<kebab-title>.proposed.md
 ```
 
+Run that helper as the complete standalone Bash command so its PostToolUse event binds the evidence to this exact session and job path.
+
 ```yaml
 human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
-Without the `wr-jtbd-mark-oversight-confirmed` call, the `jtbd-oversight-marker-discipline.sh` PreToolUse hook will DENY the marker write. A job authored through update-guide is born human-oversighted ONLY because the helper above paired the user's substance-confirm answer to the marker write. Do NOT write the marker for a job the user has not confirmed. AFK iter subprocesses MUST write `human-oversight: unconfirmed` instead (the AFK fallback enum value codified in ADR-110); the drain (`/wr-jtbd:confirm-jobs-and-personas`) later promotes it interactively. The marker is orthogonal to `status:`.
+Without the standalone `wr-jtbd-mark-oversight-confirmed` call, the `jtbd-oversight-marker-discipline.sh` PreToolUse hook will DENY the marker write. A job authored through update-guide is born human-oversighted ONLY because the helper above paired the user's substance-confirm answer to the marker write. Do NOT write the marker for a job the user has not confirmed. AFK iter subprocesses MUST write `human-oversight: unconfirmed` instead (the AFK fallback enum value codified in ADR-110); the drain (`/wr-jtbd:confirm-jobs-and-personas`) later promotes it interactively. The marker is orthogonal to `status:`.
 
 ### 7. Generate README.md index