@windyroad/architect 0.15.3 → 0.15.4

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.15.3"
+  "version": "0.15.4"
 }

package/hooks/architect-enforce-edit.sh

@@ -124,7 +124,7 @@ cat <<EOF
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
     "permissionDecision": "deny",
-    "permissionDecisionReason": "BLOCKED: Cannot edit '${BASENAME}' without architecture review. You MUST first delegate to wr-architect:agent using the Agent tool (subagent_type: 'wr-architect:agent'). The architect will review against existing decisions in docs/decisions/ and flag if a new decision should be documented. After the review completes, this file will be unblocked automatically."
+    "permissionDecisionReason": "BLOCKED: Cannot edit '${BASENAME}' without architecture review. You MUST first delegate to wr-architect:agent using the Agent tool (subagent_type: 'wr-architect:agent'). The architect will review against existing decisions in docs/decisions/ and flag if a new decision should be documented. After the review completes, this file will be unblocked automatically. ${ARCHITECT_GATE_REASON}"
   }
 }
 EOF

package/hooks/architect-plan-enforce.sh

@@ -35,7 +35,7 @@ cat <<EOF
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
     "permissionDecision": "deny",
-    "permissionDecisionReason": "BLOCKED: Architect must review the plan file before exiting plan mode. You MUST first delegate to wr-architect:agent using the Agent tool (subagent_type: 'wr-architect:agent') to review the plan against existing decisions in docs/decisions/. After the review completes, this will be unblocked automatically."
+    "permissionDecisionReason": "BLOCKED: Architect must review the plan file before exiting plan mode. You MUST first delegate to wr-architect:agent using the Agent tool (subagent_type: 'wr-architect:agent') to review the plan against existing decisions in docs/decisions/. After the review completes, this will be unblocked automatically. ${ARCHITECT_GATE_REASON}"
   }
 }
 EOF

package/hooks/lib/architect-gate.sh

@@ -8,6 +8,12 @@ _ARCHITECT_GATE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$_ARCHITECT_GATE_DIR/gate-helpers.sh"
 
 # Check architect gate marker. Returns 0 if marker is valid (allow), 1 if invalid (deny).
+# Sets ARCHITECT_GATE_REASON on failure with an explicit recovery directive
+# naming the wr-architect:agent subagent_type (P215 / RFC-021 — mirrors the
+# sibling REVIEW_GATE_REASON pattern in review-gate.sh). Downstream
+# enforcement hooks (architect-enforce-edit.sh, architect-plan-enforce.sh)
+# append this reason to their BLOCKED deny message so the agent sees a clear
+# recovery affordance without having to read source.
 # Usage: check_architect_gate "$SESSION_ID"
 check_architect_gate() {
   local SESSION_ID="$1"
@@ -38,6 +44,7 @@ check_architect_gate() {
         fi
         if [ "$STORED" != "$CURRENT" ]; then
           rm -f "$MARKER" "$HASH_FILE"
+          ARCHITECT_GATE_REASON="Decision drift detected — docs/decisions/ changed substantively since the last architect review. Re-delegate to wr-architect:agent via the Agent tool (subagent_type: 'wr-architect:agent') to refresh the marker."
           return 1  # Drift detected, deny
         else
           touch "$MARKER"  # Slide TTL window forward
@@ -49,10 +56,12 @@ check_architect_gate() {
       fi
     else
       rm -f "$MARKER"
+      ARCHITECT_GATE_REASON="Architect review expired (${AGE}s old, TTL ${TTL_SECONDS}s). Re-delegate to wr-architect:agent via the Agent tool (subagent_type: 'wr-architect:agent') to refresh the marker."
       return 1  # TTL expired, deny
     fi
   fi
 
+  ARCHITECT_GATE_REASON="No architect review marker found for this session. Delegate to wr-architect:agent via the Agent tool (subagent_type: 'wr-architect:agent') so the architect can review and create the marker."
   return 1  # No marker, deny
 }
 

package/hooks/test/architect-gate.bats

@@ -30,3 +30,59 @@ teardown() {
   ARCHITECT_TTL=0 run check_architect_gate "$TEST_SESSION"
   [ "$status" -ne 0 ]
 }
+
+# P215 / RFC-021 — ARCHITECT_GATE_REASON behaviour. The gate must expose a
+# differentiated reason per failure mode (no marker / TTL expired / drift
+# detected) so the downstream deny message carries a clear recovery directive.
+# Mirrors sibling REVIEW_GATE_REASON pattern in jtbd/voice-tone/style-guide
+# review-gate.sh.
+
+@test "ARCHITECT_GATE_REASON names re-delegate directive when no marker" {
+  ARCHITECT_GATE_REASON=""
+  check_architect_gate "$TEST_SESSION" || true
+  [[ "$ARCHITECT_GATE_REASON" == *"wr-architect:agent"* ]]
+  [[ "$ARCHITECT_GATE_REASON" == *"Agent tool"* ]]
+}
+
+@test "ARCHITECT_GATE_REASON names re-delegate directive when TTL expired" {
+  touch "/tmp/architect-reviewed-${TEST_SESSION}"
+  ARCHITECT_GATE_REASON=""
+  ARCHITECT_TTL=0 check_architect_gate "$TEST_SESSION" || true
+  [[ "$ARCHITECT_GATE_REASON" == *"expired"* ]]
+  [[ "$ARCHITECT_GATE_REASON" == *"wr-architect:agent"* ]]
+  [[ "$ARCHITECT_GATE_REASON" == *"refresh the marker"* ]]
+}
+
+@test "ARCHITECT_GATE_REASON names drift directive when stored hash differs" {
+  # Set up project root with a docs/decisions directory and a stored hash that
+  # differs from the current substance hash to force the drift branch.
+  TEST_PROJECT_DIR=$(mktemp -d)
+  mkdir -p "$TEST_PROJECT_DIR/docs/decisions"
+  echo "# ADR-001 current content" > "$TEST_PROJECT_DIR/docs/decisions/001-x.md"
+  touch "/tmp/architect-reviewed-${TEST_SESSION}"
+  echo "stale-hash-that-will-not-match" > "/tmp/architect-reviewed-${TEST_SESSION}.hash"
+  ARCHITECT_GATE_REASON=""
+  CLAUDE_PROJECT_DIR="$TEST_PROJECT_DIR" check_architect_gate "$TEST_SESSION" || true
+  rm -rf "$TEST_PROJECT_DIR"
+  [[ "$ARCHITECT_GATE_REASON" == *"drift"* ]] || [[ "$ARCHITECT_GATE_REASON" == *"changed"* ]]
+  [[ "$ARCHITECT_GATE_REASON" == *"wr-architect:agent"* ]]
+  [[ "$ARCHITECT_GATE_REASON" == *"refresh the marker"* ]]
+}
+
+@test "architect-enforce-edit deny output includes ARCHITECT_GATE_REASON directive" {
+  HOOK="$SCRIPT_DIR/architect-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  mkdir -p docs/decisions
+  echo "# adr stub" > docs/decisions/001-x.md
+  json="{\"tool_input\":{\"file_path\":\"$PWD/src/x.ts\"},\"session_id\":\"deny-test-$$\"}"
+  run bash -c "echo '$json' | bash '$HOOK'"
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"wr-architect:agent"* ]]
+  # No marker exists for this fresh session — deny reason must explicitly
+  # name the re-delegate directive (not vague "review required").
+  [[ "$output" == *"No architect review marker"* ]] || [[ "$output" == *"marker"* ]]
+}

package/package.json

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