@windyroad/itil 0.19.1-preview.194 → 0.19.2-preview.196

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-itil",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "description": "ITIL-aligned IT service management for Claude Code"
 }

package/hooks/hooks.json

@@ -6,6 +6,12 @@
     "UserPromptSubmit": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-gate.sh" }] }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/manage-problem-enforce-create.sh" }]
+      }
+    ],
     "Stop": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-review.sh" }] }
     ]

package/hooks/lib/create-gate.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Shared gate logic for new-ticket creation enforcement (P119).
+#
+# Sourced by manage-problem-enforce-create.sh. Provides:
+#   check_create_gate     — returns 0 if Step 2 marker present (allow), 1 if absent (deny)
+#   create_gate_deny      — emits PreToolUse deny JSON
+#   create_gate_parse_err — emits parse-error fallback (exit 0, no deny)
+#
+# Why a separate helper from lib/review-gate.sh:
+# review-gate.sh enforces a per-session "policy was reviewed" marker with
+# TTL + drift detection (the policy file's hash is stored alongside the
+# marker; mismatch invalidates the gate). The Step-2 grep marker has
+# different semantics — it records "this session has run the duplicate
+# check at least once" — and has neither a policy file nor drift-relevant
+# state. Per architect approval (P119): keep review-gate.sh untouched and
+# add a sibling helper rather than overload review-gate semantics.
+#
+# Marker convention: /tmp/manage-problem-grep-${SESSION_ID}
+#
+# Per-session scope is intentional (per architect direction A): a single
+# /wr-itil:manage-problem invocation may write multiple tickets (Step 4b
+# multi-concern split writes 2-N consecutive .open.md files); per-grep
+# scope would block split-create after the first Write.
+#
+# References:
+#   ADR-009 — gate marker lifecycle (covers session-scoped /tmp markers).
+#   ADR-038 — progressive disclosure (deny message stays terse + actionable).
+#   ADR-013 Rule 1 — deny redirects to /wr-itil:manage-problem where
+#                    Step 2 fires AskUserQuestion if duplicates exist.
+#
+# Empty SESSION_ID fallback: returns 1 (no marker) — fail-closed by
+# default. Hook callers may treat empty session_id as parse failure
+# and exit 0 without deny (parity with jtbd-enforce-edit.sh).
+
+# Returns 0 if the Step 2 grep marker exists for SESSION_ID; 1 otherwise.
+# Empty SESSION_ID => returns 1 (no marker).
+#
+# Usage: if check_create_gate "$SESSION_ID"; then exit 0; fi
+check_create_gate() {
+  local SESSION_ID="$1"
+  [ -n "$SESSION_ID" ] || return 1
+  [ -f "/tmp/manage-problem-grep-${SESSION_ID}" ]
+}
+
+# Writes the Step 2 grep marker for SESSION_ID. Empty SESSION_ID => no-op.
+# Idempotent — safe to call more than once per session.
+#
+# Usage: mark_step2_complete "$SESSION_ID"
+mark_step2_complete() {
+  local SESSION_ID="$1"
+  [ -n "$SESSION_ID" ] || return 0
+  : > "/tmp/manage-problem-grep-${SESSION_ID}"
+}
+
+# Emit fail-closed deny JSON for PreToolUse hooks.
+# Usage: create_gate_deny "BLOCKED: <reason>"
+create_gate_deny() {
+  local REASON="$1"
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+}
+
+# Emit fail-closed deny JSON for parse failures.
+# Currently unused — empty session_id and empty file_path both exit 0
+# without deny per parity with jtbd-enforce-edit.sh. Retained for
+# symmetry with review-gate.sh in case a future caller wants strict mode.
+create_gate_parse_error() {
+  cat <<'EOF'
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
+    "permissionDecisionReason": "BLOCKED: Could not parse hook input. Gate is fail-closed." } }
+EOF
+}

package/hooks/manage-problem-enforce-create.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# P119: PreToolUse:Write enforcement hook for new problem ticket creation.
+#
+# BLOCKS Write to docs/problems/<NNN>-*.<status>.md when the file does not
+# yet exist on disk and the per-session Step-2 grep marker is absent.
+# Marker is set by /wr-itil:manage-problem Step 2 (duplicate-check) at the
+# end of its grep pass — present marker means the agent has run the
+# duplicate-check for this session and may write new tickets.
+#
+# Out of scope (allow-listed):
+#   - docs/problems/README.md  — regenerated by Steps 5/6/7 (chicken-and-egg)
+#   - Existing files           — Edit-flow / status transitions are
+#                                governed by /wr-itil:transition-problem,
+#                                not new-ticket creation
+#   - Edit tool                — only Write is gated; Edit on existing
+#                                tickets is normal status-transition shape
+#   - Non-ticket basenames     — only docs/problems/<NNN>-*.md ticket-shaped
+#                                paths are gated (NOTES.md, archive/, etc.
+#                                are project housekeeping, not tickets)
+#
+# ADR-031 forward-compat: matcher uses docs/problems/ prefix + numeric
+# basename, agnostic to current suffix-based layout (docs/problems/NNN-*.<status>.md)
+# vs. future per-state subdirectory layout (docs/problems/<state>/NNN-*.md).
+#
+# References:
+#   ADR-009 — gate marker lifecycle (per-session /tmp markers).
+#   ADR-013 Rule 1 — deny redirects to /wr-itil:manage-problem where
+#                    Step 2 fires AskUserQuestion if duplicates exist.
+#   ADR-022 — problem lifecycle (status suffixes covered: open / known-error /
+#             verifying / parked).
+#   ADR-038 — progressive disclosure (deny message stays terse + actionable).
+#   P119    — agent bypasses Step 2 by writing tickets directly.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/create-gate.sh
+source "$SCRIPT_DIR/lib/create-gate.sh"
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('file_path', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only gate the Write tool. Edit on existing tickets is the
+# transition-problem surface, not the new-ticket surface.
+if [ "$TOOL_NAME" != "Write" ]; then
+  exit 0
+fi
+
+# Empty file_path or session_id — fail-open (mirror jtbd-enforce-edit.sh).
+# Empty session_id with a real file_path could be a hook harness call;
+# do not deny on parse-incomplete input.
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+# Match docs/problems/ paths only. Both absolute (project-root prefixed)
+# and relative shapes are accepted because Claude Code passes absolute
+# paths in tool_input.file_path but tests and direct invocations may
+# use relative paths.
+case "$FILE_PATH" in
+  *docs/problems/*) ;;
+  *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Allow-list: docs/problems/README.md is regenerated by Steps 5/6/7.
+# Gating it would chicken-and-egg the skill itself.
+if [ "$BASENAME" = "README.md" ]; then
+  exit 0
+fi
+
+# Only gate ticket-shaped basenames: NNN-... (3-digit prefix).
+# Non-ticket files (NOTES.md, archive/index.md, etc.) are project
+# housekeeping and don't need the duplicate-check.
+case "$BASENAME" in
+  [0-9][0-9][0-9]-*) ;;
+  *) exit 0 ;;
+esac
+
+# Existing file — Edit-flow / status-transition path. Only block
+# new-file creation (the Write that materialises a brand-new ticket).
+if [ -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# New ticket Write: gate on the Step-2 grep marker.
+if check_create_gate "$SESSION_ID"; then
+  exit 0
+fi
+
+create_gate_deny "BLOCKED: Cannot Write '${BASENAME}' under docs/problems/ without running /wr-itil:manage-problem Step 2 (duplicate-check) first. New problem tickets MUST be created via the skill so the duplicate-prevention grep fires before the file lands. Invoke the Skill tool with skill='wr-itil:manage-problem' and a description of the new problem; Step 2 will grep for related existing tickets and surface any matches via AskUserQuestion before creating the new ticket. (P119)"
+exit 0

package/hooks/test/manage-problem-enforce-create.bats

@@ -0,0 +1,188 @@
+#!/usr/bin/env bats
+
+# P119: manage-problem-enforce-create.sh PreToolUse hook must block new-file
+# Write to docs/problems/<NNN>-*.<status>.md until /wr-itil:manage-problem
+# Step 2 (duplicate-check) has run for the current session.
+#
+# Marker: /tmp/manage-problem-grep-${SESSION_ID} (set by Step 2 grep
+# completion). Per-session scope so a single skill invocation can write
+# multiple tickets (Step 4b multi-concern split) without re-grep blocking.
+#
+# Per feedback_behavioural_tests.md (P081): behavioural assertions —
+# simulate the hook's payload on stdin and assert on emitted JSON
+# permissionDecision and exit status. No source-grep on hook content.
+#
+# ADR-031 forward-compat: matcher uses docs/problems/ prefix +
+# numeric-prefix basename test, agnostic to current suffix-based
+# layout vs future per-state subdirectory layout.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/manage-problem-enforce-create.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  mkdir -p docs/problems
+  SID="mp-create-test-$$-$RANDOM"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  rm -f "/tmp/manage-problem-grep-${SID}"
+}
+
+# Helper: run the hook with mock JSON for a Write tool call to file_path
+run_write_hook() {
+  local file_path="$1"
+  local sid="$2"
+  local json
+  json=$(printf '{"tool_name":"Write","tool_input":{"file_path":"%s"},"session_id":"%s"}' "$file_path" "$sid")
+  echo "$json" | bash "$HOOK"
+}
+
+# Helper: run the hook with mock JSON for an Edit tool call to file_path
+run_edit_hook() {
+  local file_path="$1"
+  local sid="$2"
+  local json
+  json=$(printf '{"tool_name":"Edit","tool_input":{"file_path":"%s"},"session_id":"%s"}' "$file_path" "$sid")
+  echo "$json" | bash "$HOOK"
+}
+
+set_marker() {
+  : > "/tmp/manage-problem-grep-${SID}"
+}
+
+# --- Core deny path: new-file Write without marker ---
+
+@test "deny: Write to new docs/problems/999-foo.open.md without marker" {
+  run run_write_hook "$PWD/docs/problems/999-foo.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"manage-problem"* ]]
+}
+
+@test "deny message names the skill the agent must invoke" {
+  run run_write_hook "$PWD/docs/problems/999-foo.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"/wr-itil:manage-problem"* ]]
+}
+
+# --- Allow paths ---
+
+@test "allow: Write to new docs/problems/999-foo.open.md WITH marker" {
+  set_marker
+  run run_write_hook "$PWD/docs/problems/999-foo.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: marker permits multiple consecutive Writes (multi-concern split, Step 4b)" {
+  set_marker
+  run run_write_hook "$PWD/docs/problems/998-foo.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+  run run_write_hook "$PWD/docs/problems/999-bar.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "allow: Write to docs/problems/README.md regardless of marker" {
+  # README is regenerated by Steps 5/6/7 — chicken-and-egg per ticket Out of Scope
+  run run_write_hook "$PWD/docs/problems/README.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "allow: Edit (not Write) to existing ticket regardless of marker" {
+  echo "stub" > docs/problems/042-existing.open.md
+  run run_edit_hook "$PWD/docs/problems/042-existing.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "allow: Write to existing ticket file (overwrite) regardless of marker" {
+  # Existing file = not a new ticket creation — Edit-flow / status transitions
+  # are governed by /wr-itil:transition-problem, not this hook.
+  echo "stub" > docs/problems/042-existing.open.md
+  run run_write_hook "$PWD/docs/problems/042-existing.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "allow: Write to non-docs/problems path regardless of marker" {
+  run run_write_hook "$PWD/src/component.tsx" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "allow: Write to docs/problems/ non-numeric basename (e.g. NOTES.md)" {
+  # Only docs/problems/<NNN>-*.md ticket-shaped paths are gated. Other
+  # docs in this directory (e.g. NOTES.md, archive/index.md) are not
+  # tickets and don't need the duplicate-check.
+  run run_write_hook "$PWD/docs/problems/NOTES.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# --- Status-suffix coverage (ADR-022 lifecycle) ---
+
+@test "deny: new .known-error.md without marker" {
+  run run_write_hook "$PWD/docs/problems/999-foo.known-error.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+@test "deny: new .verifying.md without marker" {
+  run run_write_hook "$PWD/docs/problems/999-foo.verifying.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+@test "deny: new .parked.md without marker" {
+  run run_write_hook "$PWD/docs/problems/999-foo.parked.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# --- Tool-name and edge cases ---
+
+@test "allow: empty session_id (fail-open for parse failure parity with sibling hooks)" {
+  # Mirror jtbd-enforce-edit.sh: empty session_id => exit 0 without deny.
+  run bash -c "echo '{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$PWD/docs/problems/999-foo.open.md\"}}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  # No deny — empty session is the parse-error / fallback shape
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]] || skip "fail-closed parse error is also acceptable; assert in parse-failure test"
+}
+
+@test "allow: empty file_path exits 0 without action" {
+  run bash -c "echo '{\"tool_name\":\"Write\",\"tool_input\":{},\"session_id\":\"$SID\"}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# --- ADR-031 forward-compat: per-state subdirectory shape ---
+
+@test "deny: hypothetical ADR-031 layout docs/problems/open/999-foo.md without marker" {
+  # If/when ADR-031 lands and tickets move to docs/problems/<state>/<NNN>-...md,
+  # the hook must still gate them. Matcher should be path-prefix +
+  # numeric-prefix basename, not suffix-based.
+  mkdir -p docs/problems/open
+  run run_write_hook "$PWD/docs/problems/open/999-foo.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# --- Marker hygiene ---
+
+@test "marker file presence is the gate signal — touching marker after first deny unblocks subsequent Write" {
+  run run_write_hook "$PWD/docs/problems/999-foo.open.md" "$SID"
+  [[ "$output" == *"BLOCKED"* ]]
+  set_marker
+  run run_write_hook "$PWD/docs/problems/999-foo.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.19.1-preview.194",
+  "version": "0.19.2-preview.196",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/skills/manage-problem/SKILL.md

@@ -221,9 +221,18 @@ Before creating, search existing problems for similar issues. The user may not k
    - "I found existing problems that may be related: P011 (stuck saving, CLOSED), P023 (foul drawn garbled, OPEN). Would you like to: (a) Update an existing problem, (b) Create a new problem anyway, (c) Cancel?"
 5. If the user chooses to update, switch to the update flow for that problem ID
 6. If no matches found, proceed to create
+7. **After the grep completes** (whether duplicates were found or not), write the per-session create-gate marker so the `PreToolUse:Write` hook (`packages/itil/hooks/manage-problem-enforce-create.sh`, P119) allows the subsequent Write of the new `.open.md` file. The marker is `/tmp/manage-problem-grep-${SESSION_ID}` and the agent should write it via Bash:
+
+   ```bash
+   : > "/tmp/manage-problem-grep-${CLAUDE_SESSION_ID:-$(echo "${CLAUDE_HOOK_SESSION_ID:-default}")}"
+   ```
+
+   In practice the session ID is supplied by the hook payload, not as an env var — the simplest portable pattern is to ask Claude Code to run a one-line Bash that touches the marker using whatever session_id is available in the current invocation. The exact command shape depends on the runtime; the contract is that the file `/tmp/manage-problem-grep-<session-id>` exists by the time Step 5's Write fires. Per architect direction, the marker is per-session (single marker covers all new tickets for the rest of this session), enabling Step 4b multi-concern splits and same-session unrelated-ticket creation without re-running the grep.
 
 **Search strategy**: Search problem filenames AND file content. A match on the filename (kebab-case title) or the Description/Symptoms sections counts. Cast a wide net — false positives are cheap (user chooses), but false negatives mean duplicate problems.
 
+**Hook contract (P119)**: writing a `.open.md` (or any `.<status>.md`) file under `docs/problems/` without first running this Step 2 grep + marker-touch is blocked by the `manage-problem-enforce-create.sh` PreToolUse hook with a `permissionDecision: deny` directing the agent back to this skill. Agents that try to bypass the skill (e.g. mid-retrospective inline capture, post-mortem wrap-up, or any "I'll just write it directly" shortcut) will hit the deny and be redirected here. Do not work around the deny by setting the marker manually — the marker exists to record that this Step 2 ran, and a marker without a grep is the audit-trail gap P119 closes.
+
 ### 3. For new problems: Assign the next ID
 
 Compute the next ID as the **max of the local and origin highest IDs**, plus one, zero-padded to 3 digits. Comparing against `origin/<base>` is required by ADR-019 (confirmation criterion 2): without it, parallel sessions can mint the same ID for different problems and force a destructive surgical rebase on push (P040 incident).

package/skills/report-upstream/SKILL.md

@@ -12,6 +12,8 @@ This skill implements the contract documented in [ADR-024](../../../docs/decisio
 
 [ADR-033](../../../docs/decisions/033-report-upstream-classifier-problem-first.proposed.md) (Report-upstream classifier is problem-first) partially supersedes ADR-024 Decision Outcome **Steps 3 and 5 only** — the classifier is problem-first with best-fit backward-compat fallback (per Step 3 below), and the structured default body is problem-shaped (per Step 5 below). ADR-024 Steps 1, 2, 4, 6, 7, 8 and all Consequences / Confirmation clauses remain in force unchanged.
 
+The **ADR-024 amendment of 2026-04-25 (P070)** adds Step 4b (dedup check — own re-run + third-party search via `gh issue list --search` + inline LLM semantic match) and Step 5c (comment path — `gh issue comment` with cross-reference body when dedup match found). The maintainer-annoyance risk evaluator named in the P070 Direction decision is deferred to compose with the `wr-risk-scorer:external-comms` subagent declared in ADR-028 (per ADR-028 line 117 — third-evaluator extension point); the AFK auto-comment branch is on the interim **static heuristic** described in Step 4b until that evaluator lands. See Step 4b below.
+
 ## Invocation
 
 ```
@@ -110,7 +112,108 @@ The local ticket is **security-classified** if any of:
 - The ticket body has a `## Security classification` section.
 - The CLI `--classification security` argument was passed.
 
-If security-classified, route to Step 6. Otherwise, route to Step 5 (public-issue path).
+If security-classified, route to Step 6. Otherwise, route to Step 4b (dedup check) before Step 5 (public-issue path).
+
+### 4b. Dedup check (P070)
+
+This step is governed by the [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) 2026-04-25 amendment, which adds dedup checking to the Decision Outcome step list (P070). Two duplication windows close at the same insertion point: own re-run (4b.1) and third-party search (4b.2). Both branches share the same AskUserQuestion surface and the same AFK halt-and-save behaviour.
+
+> **Serves**: JTBD-004 (cross-repo coordination — dedup is the difference between coordination and spam), JTBD-001 (solo developer "without slowing down" — dedup protects the user from policing upstream duplicates manually), JTBD-006 (AFK persona — halt-and-surface protects loops from duplicate-firing), JTBD-101 (clear pattern — pattern ships without a duplication hole).
+
+#### 4b.1. Own re-run check
+
+Detect whether the local ticket already records a previous upstream report. The `## Reported Upstream` section is written by Step 7 (cross-reference back-write) on a successful prior invocation; its presence means the skill has already filed (or commented) for this local ticket.
+
+```bash
+LOCAL_URL=$(grep -A5 '^## Reported Upstream' "$LOCAL_TICKET" | grep -oE 'https?://[^ )]+' | head -1)
+if [ -n "$LOCAL_URL" ]; then
+  echo "Local ticket P${LOCAL_ID} already records an existing upstream report: $LOCAL_URL"
+  # Branch interactive vs AFK below.
+fi
+```
+
+**Interactive branch** — use `AskUserQuestion` per ADR-013 Rule 1:
+
+- `header: "Existing upstream report"`
+- `multiSelect: false`
+- Options:
+  1. `Halt — local ticket already records ${LOCAL_URL}` (Recommended) — abort the invocation; the existing report is current.
+  2. `Comment on the existing upstream report` — route to Step 5c with the existing URL's issue number; appropriate when new evidence has emerged since the previous report.
+  3. `File a new upstream issue anyway (override)` — explicit override after user has reviewed the existing record and judged the second filing warranted (e.g. previous report was closed without resolution and a fresh tracker is needed).
+
+**AFK / non-interactive branch** — apply the **interim static heuristic** (no subagent dispatch; the maintainer-annoyance risk evaluator is deferred per ADR-028 line 117 — see "AFK static heuristic" below). Default action: halt and save the drafted report to the local ticket's `## Drafted Upstream Report` section; do NOT auto-comment. The static heuristic remains in place until `wr-risk-scorer:external-comms` ships, at which point the AFK branch wires the gate combination (maintainer-annoyance + leak gate, both within appetite) per the ticket Direction decision (2026-04-21).
+
+#### 4b.2. Third-party search
+
+Detect whether a different reporter (or another agent in a parallel session) has already filed a similar issue against the upstream. The Direction decision (2026-04-21) pins a two-stage mechanism: a `gh issue list --search` pre-filter that trims candidates to ~5-10, followed by an **inline LLM semantic match** that judges each candidate's body against the proposed report.
+
+```bash
+# Stage 1: gh-search pre-filter on title keywords (cheap, ~500ms-2s).
+KEYWORDS=$(extract_3-5_keywords_from "$LOCAL_TICKET_TITLE + $LOCAL_TICKET_DESCRIPTION")
+MATCHES=$(gh issue list \
+  --repo "$UPSTREAM_OWNER_REPO" \
+  --state all \
+  --search "$KEYWORDS" \
+  --json number,title,state,url \
+  --limit 10)
+```
+
+For each candidate returned by Stage 1, fetch the full body and run **Stage 2 — inline LLM semantic judgement**:
+
+```bash
+# Stage 2: per-candidate body fetch + inline classification.
+for n in $(echo "$MATCHES" | jq -r '.[].number'); do
+  CANDIDATE=$(gh issue view "$n" --repo "$UPSTREAM_OWNER_REPO" --json title,body,state,url)
+  # Inline LLM judgement: read {local ticket Description + Symptoms, candidate title + body}
+  # and return one of: same-problem | different-problem | uncertain.
+  # No subagent dispatch — Direction decision 2026-04-21 pins inline classification
+  # for simplicity. Promotion to a `wr-itil:dedup-check` subagent is a future
+  # ADR amendment if architect review later flags context-isolation concerns.
+done
+```
+
+Notes on inline LLM classification:
+
+- **No subagent dispatch.** The skill's main-agent context already has the local ticket loaded (Step 1) and the candidate body in scope after `gh issue view`. The Direction decision (2026-04-21) pins inline classification to keep the dedup affordable; the gh-search pre-filter trims input to ~5-10 candidates so the inline reads stay bounded.
+- **Verdicts**: `same-problem` (route to AskUserQuestion with the matched URL); `different-problem` (skip, continue); `uncertain` (always surface to user — never auto-resolve).
+- **Heuristic for "same problem"**: same root cause described, overlapping symptoms, same affected component or scoped npm package. Different reproduction environment alone does NOT downgrade to `different-problem` — environment heterogeneity is normal.
+
+If Stage 2 produces one or more `same-problem` matches, surface them to the user in interactive mode:
+
+- `header: "Existing upstream issue may match"`
+- `multiSelect: false`
+- Options:
+  1. `Comment on #<N> (Recommended) — <title>` — one option per `same-problem` match; routes to Step 5c with that issue number.
+  2. `File a new upstream issue anyway (override)` — explicit override; user has reviewed the matches and judged them distinct.
+  3. `Cancel` — abort without filing or commenting.
+
+`uncertain` matches surface alongside `same-problem` matches with their verdict labelled, so the user can review. The skill never auto-resolves an `uncertain` verdict.
+
+**AFK / non-interactive branch** — apply the same interim static heuristic as 4b.1: halt and save the drafted report to the local ticket's `## Drafted Upstream Report` section. The third-party-match auto-comment path requires the deferred `wr-risk-scorer:external-comms` gate (maintainer-annoyance + leak), so the AFK branch must NOT auto-comment under the static heuristic.
+
+#### AFK static heuristic (interim, until `wr-risk-scorer:external-comms` ships)
+
+The Direction decision (2026-04-21) pins the AFK auto-comment branch on **two gates passing together**: the maintainer-annoyance risk evaluator AND the P064 external-comms leak gate, both within RISK-POLICY.md's commit-layer appetite (Low, ≤4/25). Neither gate exists yet — ADR-028 declares the `wr-risk-scorer:external-comms` subagent type but P064's implementation is open at WSJF 3.0 (Effort L), and the maintainer-annoyance evaluator was deferred by architect review on P070 to compose with the same subagent rather than ship as a separate evaluator (per ADR-028 line 117 — *"Third evaluator (licence-compliance, etc.) adding to the same gate — when it emerges, amend this ADR's evaluator list and the composite marker's `evaluator_set` component; no new ADR expected."*).
+
+**Static heuristic, valid until both gates ship**: in AFK mode, both 4b.1 and 4b.2 default to **halt and save the drafted report**. No auto-comment, no auto-file. The drafted report is appended to the local ticket's `## Drafted Upstream Report` section so the user can review and act manually on return. This matches JTBD-006's "does not trust the agent to make judgement calls" stance — the conservative default is the right interim behaviour.
+
+**Re-wire trigger**: when `wr-risk-scorer:external-comms` lands (ADR-028 implementation, P064 closure), amend this section to invoke both evaluators and proceed with auto-comment ONLY when both verdicts return PASS within appetite. Update the AFK behaviour summary table accordingly. Until then, the static heuristic stands.
+
+**Drafted Upstream Report save format** (used by both 4b.1 and 4b.2 AFK halts; mirrors the security-path halt pattern from Step 6 per ADR-024 Consequences lines 116, 123):
+
+```markdown
+## Drafted Upstream Report
+
+- **Drafted**: <YYYY-MM-DD>
+- **Target upstream**: <upstream-repo-url>
+- **Halt reason**: dedup match (own re-run | third-party `same-problem`) — interim static heuristic awaiting `wr-risk-scorer:external-comms` (ADR-028 / P064)
+- **Matched URL(s)**: <existing-issue-or-report-URL(s)>
+- **Drafted body**:
+
+  <the body that would have been posted as a `gh issue comment` or `gh issue create`, ready for manual copy-paste review>
+```
+
+The halt is a loop-stopping event for AFK orchestrators — same pattern as the security-path halt-and-surface branch — so the user sees the dedup match on return rather than the orchestrator silently auto-commenting.
 
 ### 5. Public-issue path
 
@@ -268,6 +371,37 @@ gh issue create \
 
 Capture the returned issue URL. The voice-tone gate per ADR-028 may delegate-and-retry; treat this as expected (see "Voice-tone gate interaction" above). Proceed to Step 7 once the issue is created.
 
+### 5c. Comment path (P070)
+
+Used when Step 4b's dedup check (own re-run or third-party search) finds a match AND the user picks the "comment instead" option. Skips `gh issue create` and posts a cross-reference comment on the existing upstream issue:
+
+```bash
+gh issue comment "${EXISTING_ISSUE_NUMBER}" \
+  --repo "${UPSTREAM_OWNER_REPO}" \
+  --body "${COMMENT_BODY}"
+```
+
+The comment body is a condensed cross-reference, not a full report restatement. Required structure:
+
+```markdown
+Seeing this from <downstream-repo-url>/<local-ticket-relative-path>.
+
+## Additional context
+
+- **Local ticket**: P<NNN> (<one-line title>)
+- **Reproduction**: <if local has a fresh repro path the existing issue lacks; otherwise omit>
+- **Environment**: <if differs materially from the existing issue; otherwise omit>
+- **Hypothesis**: <if local has a contradictory or extending root-cause hypothesis; otherwise omit>
+
+This issue is tracked locally as P<NNN> in the downstream project's `docs/problems/` directory.
+```
+
+Empty subsections are skipped — the comment should add information, not restate what the existing issue already records. If none of the four "additional context" subsections has content, the comment defaults to a one-line acknowledgement: `Seeing this from <downstream-repo-url>/<local-ticket-relative-path>. Tracked locally as P<NNN>.` This is still useful — it tells the upstream maintainer they have a downstream witness — without spamming the thread with redundant content.
+
+The voice-tone gate per ADR-028 also fires on `gh issue comment` (per the canonical hook's regex list at ADR-028 line 61); treat the deny-plus-delegate-and-retry as expected, same as Step 5.
+
+Capture the returned comment URL (gh prints `https://github.com/<owner>/<repo>/issues/<n>#issuecomment-<id>`). The Step 7 back-write records this as the cross-reference URL with disclosure path `commented-on-existing-issue`. Proceed to Step 7.
+
 ### 6. Security path
 
 Fetch the upstream's `SECURITY.md`:
@@ -318,7 +452,7 @@ After the upstream issue or advisory is created (or drafted-and-saved in the sec
    - **URL**: <upstream-issue-or-advisory-url>
    - **Reported**: <YYYY-MM-DD>
    - **Template used**: <template-name-or-"structured default">
-   - **Disclosure path**: <public issue | security advisory | drafted-and-saved (mailbox / out-of-band)>
+   - **Disclosure path**: <public issue | security advisory | drafted-and-saved (mailbox / out-of-band) | commented-on-existing-issue (Step 5c, P070)>
    - **Cross-reference confirmed**: <yes/no — true once the upstream issue body contains the local ticket reference>
    ```
 
@@ -334,19 +468,21 @@ If the cumulative pipeline risk lands above appetite and `AskUserQuestion` is un
 
 ## AFK behaviour summary
 
-Three distinct AFK branches per the architect review of ADR-024 + ADR-013 Rule 6:
+Five distinct AFK branches per the architect reviews of ADR-024, ADR-013 Rule 6, and the P070 dedup amendment:
 
 | Branch | AFK behaviour | Authority |
 |---|---|---|
 | Public-issue path (Step 5) | Proceeds. Voice-tone gate per ADR-028 may delegate-and-retry; that is the expected extra turn. | ADR-028 line 126 |
+| Dedup match — Step 4b halt (own re-run OR third-party `same-problem`) | Save drafted report to local ticket's `## Drafted Upstream Report` section. **Halt the orchestrator** — loop-stopping event. Interim static heuristic; auto-comment branch deferred until `wr-risk-scorer:external-comms` ships (ADR-028 line 117). | ADR-024 amendment 2026-04-25 (P070); Direction decision 2026-04-21 |
 | Security path with declared channel (Step 6, GitHub Advisories) | Proceeds via `gh api .../security-advisories`. | ADR-024 Decision Outcome step 6 |
 | Security path with `security@` / other / missing-SECURITY.md (Step 6) | Save drafted report to local ticket's `## Drafted Upstream Report` section. **Halt the orchestrator** — loop-stopping event. AFK orchestrators must never auto-report a security-classified ticket. | ADR-024 Consequences lines 116, 123 |
 | Above-appetite commit (Step 8) | Skip the commit, report uncommitted state. | ADR-013 Rule 6 |
 
 ## References
 
-- [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) — primary contract this skill implements. Steps 1, 2, 4, 6, 7, 8 and all Consequences remain authoritative.
+- [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) — primary contract this skill implements. Steps 1, 2, 4, 6, 7, 8 and all Consequences remain authoritative; the 2026-04-25 amendment adds Step 4b (dedup) + Step 5c (comment path) for P070.
 - [ADR-033](../../../docs/decisions/033-report-upstream-classifier-problem-first.proposed.md) — partially supersedes ADR-024 Decision Outcome Steps 3 + 5; governs the problem-first classifier and problem-shaped structured default body.
+- [P070](../../../docs/problems/) — driver ticket for the Step 4b dedup check + Step 5c comment path; carries the 2026-04-21 Direction decision (gh search + inline LLM, no subagent dispatch) and the AFK static-heuristic interim behaviour.
 - [ADR-027](../../../docs/decisions/027-governance-skill-auto-delegation.proposed.md) — Step-0 deferral rationale (held for reassessment).
 - [ADR-028](../../../docs/decisions/028-voice-tone-gate-external-comms.proposed.md) — voice-tone gate on `gh issue create` and `gh api .../security-advisories`.
 - [ADR-013](../../../docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md) — interaction policy; Rule 1 governs Step 6 missing-SECURITY.md `AskUserQuestion`; Rule 6 governs the commit-gate AFK branch.

package/skills/report-upstream/test/report-upstream-contract.bats

@@ -158,3 +158,92 @@ setup() {
   [ "$status" -eq 0 ]
   [ "${#lines[@]}" -ge 2 ]
 }
+
+# ─── P070 dedup contract (Step 4b + Step 5c + AFK static heuristic) ────────────
+#
+# P070 inserts a dedup check between security-path routing (Step 4) and the
+# outbound `gh` call (Steps 5 / 6). Two duplication windows close at the same
+# insertion point: own re-run (local ticket already has `## Reported Upstream`)
+# and third-party search (different reporter filed similar). Step 5c adds a
+# comment-on-existing-issue path used when the dedup branch finds a match.
+#
+# Per architect verdict on P070: the maintainer-annoyance risk evaluator is
+# deferred until ADR-028 / P064's `wr-risk-scorer:external-comms` subagent
+# ships (ADR-028 line 117 anticipates third evaluators). The interim AFK
+# branch uses a static heuristic — no subagent dispatch — that defaults to
+# halt-and-save.
+
+@test "report-upstream: SKILL.md contains a Step 4b dedup check (P070)" {
+  run grep -nE '^### 4b\.' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md Step 4b.1 detects own-re-run via ## Reported Upstream (P070)" {
+  # Own-re-run branch: grep the local ticket for an existing `## Reported
+  # Upstream` URL before firing a second upstream report.
+  run grep -nE 'Reported Upstream.*(grep|already|existing|previous)' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md Step 4b.2 third-party search uses gh issue list --search (P070)" {
+  # Third-party branch: `gh issue list --repo ... --search ...` against the
+  # upstream's existing issues. Required tokens.
+  run grep -F 'gh issue list' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  # `--` before the pattern stops grep from treating `--search` as a flag.
+  run grep -F -- '--search' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md Step 4b.2 uses inline LLM judge, not subagent dispatch (P070 Direction decision 2026-04-21)" {
+  # Direction decision pins inline LLM check inside the skill's own session.
+  # No `wr-itil:dedup-check` subagent dispatch; future promotion is a separate
+  # ADR amendment.
+  run grep -iE 'inline.*llm|inline semantic|inline.*judge|inline classification' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md contains Step 5c comment path with gh issue comment (P070)" {
+  # Step 5c: when dedup match found AND user picks "comment instead", run
+  # `gh issue comment <number>` rather than `gh issue create`.
+  run grep -nE '^### 5c\.' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'gh issue comment' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md Step 5c records commented-on-existing-issue disclosure path (P070 + ADR-024 amendment)" {
+  # ADR-024 amendment extends the disclosure-path enumeration. The literal
+  # string MUST appear in the SKILL.md so the ## Reported Upstream back-write
+  # records the new path.
+  run grep -F 'commented-on-existing-issue' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md AFK branch uses static heuristic, defers maintainer-annoyance evaluator (P070 interim per ADR-028 line 117)" {
+  # Architect verdict: maintainer-annoyance evaluator deferred. AFK branch
+  # uses a static heuristic and defaults to halt-and-save. The SKILL.md must
+  # name the deferral explicitly so future readers know why the static-heuristic
+  # path exists; once `wr-risk-scorer:external-comms` lands, this branch
+  # gets re-wired.
+  run grep -iE 'static heuristic|interim.*heuristic|heuristic.*interim' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -iE 'wr-risk-scorer:external-comms|external-comms.*evaluator' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md AFK halt-and-save writes Drafted Upstream Report section (P070 + ADR-024 Consequences)" {
+  # AFK halt branch saves the drafted report to the local ticket's
+  # `## Drafted Upstream Report` section — same pattern as the security-path
+  # halt per ADR-024 Consequences (lines 116, 123).
+  run grep -F '## Drafted Upstream Report' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "report-upstream: SKILL.md AFK behaviour summary table includes the dedup branch (P070)" {
+  # The "AFK behaviour summary" table at the bottom of the skill must list
+  # the new dedup-halt branch alongside the existing public-issue / security
+  # / above-appetite branches.
+  run grep -iE 'dedup.*halt|step 4b.*halt|halt.*dedup|halt-and-save.*dedup' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}