@windyroad/architect 0.15.5 → 0.15.6

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.15.5"
+  "version": "0.15.6"
 }

package/hooks/architect-enforce-edit.sh

@@ -5,6 +5,7 @@
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/architect-gate.sh"
+source "$SCRIPT_DIR/lib/marker-only-diff.sh"
 
 # P191 Phase 2: resolve the project root from the session signal, not the
 # hook's runtime CWD. Claude Code can launch the hook with a working directory
@@ -22,6 +23,7 @@ INPUT=$(cat)
 
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') || true
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty') || true
 
 if [ -z "$SESSION_ID" ]; then
   architect_gate_parse_error
@@ -114,6 +116,41 @@ case "$FILE_PATH" in
     exit 0 ;;
 esac
 
+# P301: marker-only-diff exemption for docs/decisions/*.md ADRs. An
+# Edit/Write that adds or updates ONLY the narrow oversight-marker
+# frontmatter grammar (`human-oversight:`, `oversight-date:`,
+# `decision-makers:`, `supersede-ticket:`) is the mechanical output of a
+# decision the user already substance-confirmed via AskUserQuestion
+# (ADR-066 contract); the architect review has nothing substantive to
+# assess. The architect-oversight-marker-discipline.sh hook remains the
+# safety net: marker-only diffs that introduce `human-oversight:
+# confirmed` still require the per-ADR session evidence marker (P348 /
+# ADR-066 amendment 2026-06-02). Mixed marker+body diffs, status:/date:
+# changes, and pure body changes fall through to the normal gate.
+case "$FILE_PATH" in
+  */docs/decisions/*.md|docs/decisions/*.md)
+    case "$TOOL_NAME" in
+      Edit)
+        _OLD=$(echo "$INPUT" | jq -r '.tool_input.old_string // empty') || _OLD=""
+        _NEW=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty') || _NEW=""
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+      Write)
+        _NEW=$(echo "$INPUT" | jq -r '.tool_input.content // empty') || _NEW=""
+        _OLD=""
+        if [ -f "$FILE_PATH" ]; then
+          _OLD=$(cat "$FILE_PATH" 2>/dev/null) || _OLD=""
+        fi
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+    esac
+    ;;
+esac
+
 # Check gate
 if check_architect_gate "$SESSION_ID"; then
   exit 0

package/hooks/lib/marker-only-diff.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Shared helper: detect "oversight-marker-only" frontmatter diffs.
+#
+# P301: ADR-066/068 oversight-marker writes to docs/decisions/ ADRs trip the
+# full architect+JTBD edit gate each batch of an `/wr-architect:review-decisions`
+# drain, producing 2-3 no-op-PASS review round-trips per batch. The marker
+# add/update is the mechanical output of a decision the user already
+# substance-confirmed via AskUserQuestion (ADR-066 contract); the gate has
+# nothing substantive to assess.
+#
+# This helper exposes `is_marker_only_diff OLD NEW` returning 0 when every
+# added/removed non-empty line matches one of the oversight-marker frontmatter
+# patterns:
+#
+#   human-oversight:   confirmed | unconfirmed | rejected-pending-supersede
+#   oversight-date:    <date>
+#   decision-makers:   <name|email>
+#   supersede-ticket:  <ticket>
+#
+# When the predicate fires PASS, the calling gate short-circuits to exit 0
+# without requiring a fresh architect / JTBD review marker. The
+# architect-oversight-marker-discipline.sh (and JTBD sibling) hooks remain
+# active as the safety net: a marker-only diff that introduces
+# `human-oversight: confirmed` still requires the per-ADR session evidence
+# marker (P348 / ADR-066 amendment 2026-06-02).
+#
+# Conservative boundary: any non-empty line outside the marker grammar
+# (frontmatter delimiters that shift position, status:/date: changes, body
+# edits) fails the predicate. The exemption is exact so it cannot be used
+# to slip decision-content edits past the gate.
+#
+# Fail-safe: if python3 is unavailable or the diff parse errors, the function
+# returns 1 (NOT marker-only) and the gate proceeds with its normal review
+# requirement.
+
+is_marker_only_diff() {
+  local old="$1"
+  local new="$2"
+
+  command -v python3 >/dev/null 2>&1 || return 1
+
+  OLD_CONTENT="$old" NEW_CONTENT="$new" python3 - <<'PYEOF'
+import os, sys, re
+try:
+    import difflib
+except Exception:
+    sys.exit(1)
+
+old = os.environ.get('OLD_CONTENT', '')
+new = os.environ.get('NEW_CONTENT', '')
+
+if old == new:
+    sys.exit(0)
+
+old_lines = old.splitlines()
+new_lines = new.splitlines()
+
+marker_pat = re.compile(
+    r'^[ \t]*(human-oversight|oversight-date|decision-makers|supersede-ticket)[ \t]*:.*$'
+)
+
+def allowed(line: str) -> bool:
+    s = line.strip()
+    if s == '':
+        return True
+    if marker_pat.match(line):
+        return True
+    return False
+
+sm = difflib.SequenceMatcher(a=old_lines, b=new_lines, autojunk=False)
+for tag, i1, i2, j1, j2 in sm.get_opcodes():
+    if tag == 'equal':
+        continue
+    for line in old_lines[i1:i2]:
+        if not allowed(line):
+            sys.exit(1)
+    for line in new_lines[j1:j2]:
+        if not allowed(line):
+            sys.exit(1)
+
+sys.exit(0)
+PYEOF
+}

package/hooks/test/architect-marker-only-exempt.bats

@@ -0,0 +1,183 @@
+#!/usr/bin/env bats
+
+# P301: architect-enforce-edit.sh exempts marker-only frontmatter diffs to
+# docs/decisions/*.md ADRs from the full architect review gate. The
+# architect-oversight-marker-discipline.sh hook remains the safety net for
+# `human-oversight: confirmed` introductions; this exemption only short-
+# circuits the enforce-edit drift/TTL gate when the diff adds/modifies
+# nothing but the narrow oversight-marker grammar.
+#
+# Behavioural — exercises the full hook with constructed PreToolUse stdin
+# JSON payloads under a sandbox project dir; asserts on stdout+exit.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/architect-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  # Engage the architect gate — only runs when docs/decisions/ exists.
+  mkdir -p docs/decisions
+  echo "# stub" > docs/decisions/001-stub.proposed.md
+  SID="marker-only-exempt-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  rm -f "/tmp/architect-reviewed-${SID}" "/tmp/architect-reviewed-${SID}.hash"
+}
+
+# Helper: run the hook with constructed JSON. Echo to a file then pipe to
+# avoid heredoc / quote-escaping headaches with multi-line content.
+run_hook_json() {
+  local json_file="$1"
+  bash "$HOOK" < "$json_file"
+}
+
+# ── Marker-only ADD: should exempt ───────────────────────────────────────
+
+@test "P301: Edit adding only human-oversight + oversight-date is exempt (no architect marker required)" {
+  adr="$PWD/docs/decisions/100-some-adr.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+date: 2026-06-08
+---
+
+# 100 some adr
+
+Body content unchanged.
+EOF
+  old=$'---\nstatus: "proposed"\ndate: 2026-06-08\n---'
+  new=$'---\nstatus: "proposed"\ndate: 2026-06-08\nhuman-oversight: unconfirmed\noversight-date: 2026-06-08\n---'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "P301: Edit updating human-oversight value (unconfirmed → confirmed) is exempt" {
+  adr="$PWD/docs/decisions/101-promote.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+human-oversight: unconfirmed
+---
+
+# 101 promote
+EOF
+  old=$'human-oversight: unconfirmed'
+  new=$'human-oversight: confirmed\noversight-date: 2026-06-08'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "P301: Edit adding rejected-pending-supersede + supersede-ticket is exempt" {
+  adr="$PWD/docs/decisions/102-rejected.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 102 rejected
+EOF
+  old=$'status: "proposed"'
+  new=$'status: "proposed"\nhuman-oversight: rejected-pending-supersede\nsupersede-ticket: P999'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Mixed marker + body: must NOT exempt ─────────────────────────────────
+
+@test "P301: Edit changing body content along with markers still gates" {
+  adr="$PWD/docs/decisions/110-mixed.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 110 mixed
+
+Original body.
+EOF
+  old=$'---\nstatus: "proposed"\n---\n\n# 110 mixed\n\nOriginal body.'
+  new=$'---\nstatus: "proposed"\nhuman-oversight: confirmed\noversight-date: 2026-06-08\n---\n\n# 110 mixed\n\nRewritten body with new policy claim.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+@test "P301: Edit changing status field (not a marker line) still gates" {
+  adr="$PWD/docs/decisions/111-status-change.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 111
+EOF
+  old=$'status: "proposed"'
+  new=$'status: "accepted"\nhuman-oversight: confirmed\noversight-date: 2026-06-08'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Pure body change: must still gate (no marker involvement) ────────────
+
+@test "P301: Edit changing only body content with no marker lines still gates" {
+  adr="$PWD/docs/decisions/120-body.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 120 body
+
+Some text.
+EOF
+  old='Some text.'
+  new='Some text. And new text.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Scope: exemption is narrow to docs/decisions/*.md ────────────────────
+
+@test "P301: marker-only diff to a NON docs/decisions/ path still gates (no path exemption)" {
+  mkdir -p "$PWD/src"
+  echo "// stub" > "$PWD/src/x.ts"
+  src="$PWD/src/x.ts"
+  old='// stub'
+  new='// stub'$'\n''human-oversight: confirmed'
+  json_file=$(mktemp)
+  jq -nc --arg p "$src" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.15.5",
+  "version": "0.15.6",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"