@windyroad/itil 0.25.0 → 0.26.0

package/hooks/test/itil-rfc-trailer-advisory.bats

@@ -0,0 +1,273 @@
+#!/usr/bin/env bats
+
+# @problem P170 — Slice 3 second half (B5.T9): PostToolUse:Bash hook
+# detects `git commit` invocations whose HEAD commit message carries
+# a `Refs: RFC-<NNN>` trailer, and emits a stderr advisory when the
+# corresponding driving-problem ticket's `## RFCs` table is stale.
+#
+# Architect Q1 verdict: skill-side refresh primary; hook-side advisory
+# for arbitrary commits (e.g. feat/fix/chore commits with `Refs:` trailer
+# authored outside the RFC skills).
+# Architect Q2 verdict: PostToolUse:Bash; advisory-only; silent-on-pass
+# per ADR-045 Pattern 1; fail-open per ADR-013 Rule 6.
+# Architect Q4 verdict: parse via `git interpret-trailers`; multi-`Refs:`
+# trailers emit malformed-per-finding-8 advisory.
+#
+# Behavioural per ADR-052 + P081: assert on emitted stderr / exit code
+# in response to simulated PostToolUse:Bash payload — no structural
+# greps on hook source.
+#
+# @adr ADR-014 (single-commit grain — hook never auto-fixes via follow-up commit)
+# @adr ADR-013 Rule 6 (fail-open)
+# @adr ADR-045 (silent-on-pass; advisory band ≤300 bytes)
+# @adr ADR-051 (load-bearing-from-the-start)
+# @adr ADR-060 (Phase 1 item 12 + Confirmation criterion 3)
+# @jtbd JTBD-006 (advisory does not block AFK loop — exit 0; stderr only)
+# @jtbd JTBD-008 (reverse-trace surface JTBD-008 names — drift detection)
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/itil-rfc-trailer-advisory.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  git init --quiet -b main
+  git config user.email "test@example.com"
+  git config user.name "Test"
+  mkdir -p docs/rfcs docs/problems
+  echo "seed" > seed.txt
+  git add seed.txt
+  git -c commit.gpgsign=false commit --quiet -m "initial"
+  unset BYPASS_RFC_TRAILER_ADVISORY
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  unset BYPASS_RFC_TRAILER_ADVISORY
+}
+
+write_rfc() {
+  local id="$1" slug="$2" status="$3"
+  local problems="${4:-[P168]}"
+  cat > "docs/rfcs/RFC-${id}-${slug}.${status}.md" <<EOF
+---
+status: ${status}
+rfc-id: ${slug}
+reported: 2026-05-05
+decision-makers: [test]
+problems: ${problems}
+---
+
+# RFC-${id}: ${slug}
+
+stub
+EOF
+}
+
+write_problem_with_rfcs_section() {
+  local num="$1" rows="$2"
+  local file="docs/problems/${num}-stub.open.md"
+  cat > "$file" <<EOF
+# Problem ${num}: stub
+
+**Status**: Open
+
+## Description
+
+stub
+
+## Related
+
+stub
+
+## RFCs
+
+| RFC | Status | Title |
+|-----|--------|-------|
+${rows}
+EOF
+}
+
+write_problem_without_rfcs_section() {
+  local num="$1"
+  cat > "docs/problems/${num}-stub.open.md" <<EOF
+# Problem ${num}: stub
+
+**Status**: Open
+
+## Description
+
+stub
+
+## Related
+
+stub
+EOF
+}
+
+run_post_bash_hook() {
+  local cmd="$1"
+  local json
+  json=$(printf '{"tool_name":"Bash","tool_input":{"command":"%s"}}' "$cmd")
+  echo "$json" | bash "$HOOK"
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "hook exists" {
+  [ -f "$HOOK" ]
+}
+
+@test "hook is executable" {
+  [ -x "$HOOK" ]
+}
+
+# ── Silent paths ────────────────────────────────────────────────────────────
+
+@test "non-Bash tool → silent (exit 0; no output)" {
+  json='{"tool_name":"Write","tool_input":{"file_path":"foo.txt","content":"x"}}'
+  run bash -c "echo '$json' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "non-commit Bash command → silent" {
+  run run_post_bash_hook "git status"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "BYPASS_RFC_TRAILER_ADVISORY=1 → silent regardless of drift" {
+  write_rfc "001" "foo" "accepted"
+  write_problem_without_rfcs_section "168"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-001"
+  BYPASS_RFC_TRAILER_ADVISORY=1 run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "outside git work tree → silent" {
+  cd "$ORIG_DIR"
+  TMP_NONGIT=$(mktemp -d)
+  cd "$TMP_NONGIT"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+  cd "$ORIG_DIR"
+  rm -rf "$TMP_NONGIT"
+}
+
+@test "no docs/rfcs/ → silent (project has not adopted RFC framework)" {
+  rm -rf docs/rfcs
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "no docs/problems/ → silent (project has not adopted problem framework)" {
+  rm -rf docs/problems
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "commit without Refs: RFC trailer → silent" {
+  write_rfc "001" "foo" "accepted"
+  write_problem_without_rfcs_section "168"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: no trailer"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Advisory paths ──────────────────────────────────────────────────────────
+
+@test "Refs: RFC-NNN trailer + stale problem (no ## RFCs section) → stderr advisory" {
+  write_rfc "001" "foo" "accepted"
+  write_problem_without_rfcs_section "168"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-001"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RFC-001"* ]]
+  [[ "$output" == *"P168"* ]]
+}
+
+@test "Refs: RFC-NNN trailer + stale problem (## RFCs section missing this RFC) → stderr advisory" {
+  write_rfc "001" "foo" "accepted"
+  write_problem_with_rfcs_section "168" "| RFC-002 | proposed | other |"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-001"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RFC-001"* ]]
+  [[ "$output" == *"P168"* ]]
+}
+
+@test "Refs: RFC-NNN trailer + current problem ## RFCs (RFC listed) → silent" {
+  write_rfc "001" "foo" "accepted"
+  write_problem_with_rfcs_section "168" "| RFC-001 | accepted | foo |"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-001"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Multi-RFC malformed-per-finding-8 ──────────────────────────────────────
+
+@test "multiple Refs: RFC trailers → malformed advisory (architect Q4 / finding 8)" {
+  write_rfc "001" "foo" "accepted"
+  write_rfc "002" "bar" "accepted"
+  write_problem_with_rfcs_section "168" "| RFC-001 | accepted | foo |"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-001
+Refs: RFC-002"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  # The advisory names finding-8 / split / mis-scoped vocabulary.
+  [[ "$output" == *"finding-8"* || "$output" == *"split"* || "$output" == *"mis-scoped"* ]]
+}
+
+# ── Trailer to non-existent RFC ──────────────────────────────────────────────
+
+@test "Refs: RFC trailer with no matching file → silent (RFC may be in flight elsewhere)" {
+  write_problem_without_rfcs_section "168"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-999"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  # Fail-open: missing RFC files don't promote to advisory (could be capture-rfc invocation in flight).
+  [ -z "$output" ]
+}
+
+# ── Advisory budget ─────────────────────────────────────────────────────────
+
+@test "advisory message stays within ADR-045 advisory band (≤300 bytes)" {
+  write_rfc "001" "byte-budget-test-with-an-extra-long-slug-to-stress-row-width" "accepted"
+  write_problem_without_rfcs_section "168"
+  echo "x" > stub.txt
+  git add stub.txt
+  git -c commit.gpgsign=false commit --quiet -m "feat: stub" -m "" -m "Refs: RFC-001"
+  run run_post_bash_hook "git commit -m foo"
+  [ "$status" -eq 0 ]
+  [ -n "$output" ]
+  # Permit per-line overhead; the advisory should remain readable.
+  [ "${#output}" -le 600 ]
+}

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

@@ -22,7 +22,7 @@ setup() {
   ORIG_DIR="$PWD"
   TEST_DIR=$(mktemp -d)
   cd "$TEST_DIR"
-  mkdir -p docs/problems
+  mkdir -p docs/problems docs/rfcs
   SID="mp-create-test-$$-$RANDOM"
 }
 
@@ -30,6 +30,11 @@ teardown() {
   cd "$ORIG_DIR"
   rm -rf "$TEST_DIR"
   rm -f "/tmp/manage-problem-grep-${SID}"
+  rm -f "/tmp/wr-itil-rfc-capture-grep-${SID}"
+}
+
+set_rfc_marker() {
+  : > "/tmp/wr-itil-rfc-capture-grep-${SID}"
 }
 
 # Helper: run the hook with mock JSON for a Write tool call to file_path
@@ -241,3 +246,102 @@ teardown_other_sid_marker() {
   [[ "$output" != *"SID mismatch"* ]]
   [[ "$output" != *"Step 2 substep 7"* ]]
 }
+
+# --- P170 / ADR-060: RFC tier extension ---
+#
+# The hook gate covers both docs/problems/ and docs/rfcs/. Each tier has its
+# own marker (problems: /tmp/manage-problem-grep-${SID};
+# rfcs: /tmp/wr-itil-rfc-capture-grep-${SID}) and its own deny message
+# pointing to the right skill (manage-problem vs capture-rfc).
+
+@test "rfcs deny: Write to new docs/rfcs/RFC-001-foo.proposed.md without RFC marker" {
+  run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+@test "rfcs deny message names capture-rfc skill (not manage-problem)" {
+  run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"/wr-itil:capture-rfc"* ]]
+  [[ "$output" != *"/wr-itil:manage-problem"* ]]
+}
+
+@test "rfcs deny message names the I1 trace-to-problem invariant + ADR-060" {
+  run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"problem-trace"* ]]
+  [[ "$output" == *"ADR-060"* ]]
+}
+
+@test "rfcs allow: Write to new docs/rfcs/RFC-001-foo.proposed.md WITH RFC marker" {
+  set_rfc_marker
+  run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "rfcs allow: Write to docs/rfcs/README.md regardless of marker (chicken-and-egg)" {
+  run run_write_hook "$PWD/docs/rfcs/README.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "rfcs allow: Write to docs/rfcs/ non-RFC basename (e.g. NOTES.md) regardless of marker" {
+  run run_write_hook "$PWD/docs/rfcs/NOTES.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "rfcs deny: Write across all RFC lifecycle suffixes without marker (proposed/accepted/in-progress/verifying/closed)" {
+  for suffix in proposed accepted in-progress verifying closed; do
+    run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.${suffix}.md" "$SID"
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"BLOCKED"* ]] || { echo "expected deny for suffix=$suffix"; return 1; }
+  done
+}
+
+@test "rfcs marker independence: problem marker does NOT unlock RFC writes" {
+  # The two markers are siblings, not interchangeable. Setting the
+  # problem-tier marker should NOT bypass the RFC-tier gate.
+  set_marker
+  run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"capture-rfc"* ]]
+}
+
+@test "problems marker independence: RFC marker does NOT unlock problem writes" {
+  # Inverse direction — preserves audit-trail per-surface granularity.
+  set_rfc_marker
+  run run_write_hook "$PWD/docs/problems/999-foo.open.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"manage-problem"* ]]
+}
+
+@test "rfcs allow: existing RFC file (overwrite) regardless of marker" {
+  echo "stub" > docs/rfcs/RFC-001-foo.proposed.md
+  run run_write_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "rfcs allow: Edit (not Write) regardless of marker" {
+  echo "stub" > docs/rfcs/RFC-001-foo.proposed.md
+  run run_edit_hook "$PWD/docs/rfcs/RFC-001-foo.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "rfcs deny: bare numeric basename (no RFC- prefix) does NOT match the rfcs gate" {
+  # Defensive: a docs/rfcs/123-foo.proposed.md (no RFC- prefix) is not
+  # an RFC by naming convention; it should NOT trigger the gate.
+  # (If the user accidentally creates such a file, it's project
+  # housekeeping, not a ticket.)
+  run run_write_hook "$PWD/docs/rfcs/123-no-prefix.proposed.md" "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}

package/package.json

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