@windyroad/architect 0.4.1-preview.161 → 0.5.0-preview.168

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-architect",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Architecture decision enforcement for Claude Code"
 }

package/hooks/architect-detect.sh

@@ -1,10 +1,28 @@
 #!/bin/bash
-# Architecture - UserPromptSubmit hook
+# Architecture - UserPromptSubmit hook (P095 / ADR-038)
 # Detects docs/decisions/ directory and injects delegation instruction.
 # The architect agent reviews changes against architectural decision records.
+#
+# Progressive disclosure (ADR-038): emit the full MANDATORY block only
+# on the first prompt of a session; subsequent prompts see a terse
+# reminder that names the gate + the delegation affordance. The
+# PreToolUse edit gate (architect-enforce-edit.sh) remains the
+# enforcement surface — the prose is a reminder, not the enforcer.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/session-marker.sh
+source "$SCRIPT_DIR/lib/session-marker.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")
 
 if [ -d "docs/decisions" ]; then
-  cat <<'HOOK_OUTPUT'
+  if has_announced "architect" "$SESSION_ID"; then
+    cat <<'HOOK_OUTPUT'
+MANDATORY architecture gate active (docs/decisions/ present). Delegate to wr-architect:agent before editing project files. See turn-1 instructions for full scope and exclusions.
+HOOK_OUTPUT
+  else
+    cat <<'HOOK_OUTPUT'
 INSTRUCTION: MANDATORY ARCHITECTURE CHECK. YOU MUST FOLLOW THIS.
 DETECTED: docs/decisions/ exists in this project.
 
@@ -41,6 +59,8 @@ docs/problems/ (problem tickets), docs/BRIEFING.md, RISK-POLICY.md,
 docs/PRODUCT_DISCOVERY.md, docs/VOICE-AND-TONE.md,
 docs/STYLE-GUIDE.md.
 HOOK_OUTPUT
+    mark_announced "architect" "$SESSION_ID"
+  fi
 else
   cat <<'HOOK_OUTPUT'
 NOTE: This project has no docs/decisions/ directory.

package/hooks/lib/session-marker.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Shared session-announcement marker helpers (P095 / ADR-038).
+#
+# Used by UserPromptSubmit hooks to gate verbose MANDATORY instruction
+# prose behind a once-per-session check. First prompt of a session emits
+# the full block AND calls mark_announced; subsequent prompts see the
+# marker via has_announced and emit only a terse reminder.
+#
+# Why no TTL or drift check (unlike review-gate.sh): announcement is
+# bookkeeping for prose verbosity, not enforcement. PreToolUse gates
+# still block unauthorised edits regardless of announcement state; the
+# delegated agent re-reads policy when it runs. Extending the marker's
+# lifetime across policy changes mid-session is safe — the gate, not
+# the announcement, is load-bearing.
+#
+# Marker path convention: /tmp/${SYSTEM}-announced-${SESSION_ID}
+# (mirrors the /tmp/${SYSTEM}-reviewed-${SESSION_ID} convention from
+# style-guide/voice-tone/risk-scorer review-gate.sh; the -announced-
+# suffix distinguishes announcement markers from clearance markers).
+#
+# Empty SESSION_ID fallback: has_announced returns 1 (not announced,
+# full block emits) and mark_announced is a no-op (no file written).
+# This covers manual hook invocation, test harnesses, and any rare
+# case where Claude Code does not pass a session_id on stdin.
+
+# Returns 0 if the hook for SYSTEM has already announced in SESSION_ID,
+# 1 otherwise. Empty SESSION_ID => returns 1 (never announced).
+#
+# Usage: has_announced "architect" "$SESSION_ID"
+has_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 1
+  [ -f "/tmp/${SYSTEM}-announced-${SESSION_ID}" ]
+}
+
+# Writes the announcement marker for SYSTEM in SESSION_ID. Empty
+# SESSION_ID => no-op. Safe to call more than once per session.
+#
+# Usage: mark_announced "architect" "$SESSION_ID"
+mark_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 0
+  : > "/tmp/${SYSTEM}-announced-${SESSION_ID}"
+}

package/hooks/test/architect-detect-once-per-session.bats

@@ -0,0 +1,106 @@
+#!/usr/bin/env bats
+
+# P095 / ADR-038: architect-detect.sh UserPromptSubmit hook must emit
+# the full MANDATORY instruction block only on the first prompt of a
+# session (identified by session_id on stdin). Subsequent prompts in
+# the same session emit only a terse reminder. New sessions or empty
+# session_ids fall back to the full block.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/architect/hooks/architect-detect.sh"
+
+  # Stub project working dir so the hook's docs/decisions/ detection fires.
+  WORKDIR="$(mktemp -d)"
+  mkdir -p "$WORKDIR/docs/decisions"
+  : > "$WORKDIR/docs/decisions/.keep"
+
+  SID="arch-detect-test-$$-$RANDOM"
+}
+
+teardown() {
+  rm -f "/tmp/architect-announced-${SID}"
+  rm -f "/tmp/architect-announced-${SID}-alt"
+  rm -rf "$WORKDIR"
+}
+
+# Helper: invoke the hook with a given session_id from stdin, while cd'd
+# into WORKDIR so the `docs/decisions` detection picks up the stub.
+run_hook() {
+  local sid="$1"
+  (cd "$WORKDIR" && echo "{\"session_id\":\"$sid\"}" | bash "$HOOK")
+}
+
+@test "architect-detect: first invocation emits the full MANDATORY block" {
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 500 ]
+  [[ "$output" == *"MANDATORY ARCHITECTURE CHECK"* ]]
+  [[ "$output" == *"wr-architect:agent"* ]]
+  [[ "$output" == *"SCOPE:"* ]]
+}
+
+@test "architect-detect: first invocation writes the announcement marker" {
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  [ -f "/tmp/architect-announced-${SID}" ]
+}
+
+@test "architect-detect: second invocation emits only a terse reminder" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  # Terse reminder is < 250 bytes; full block is > 500 bytes.
+  [ "${#output}" -lt 250 ]
+  # Terse reminder names the gate AND the delegation affordance.
+  [[ "$output" == *"architecture"* ]] || [[ "$output" == *"ARCHITECTURE"* ]]
+  [[ "$output" == *"wr-architect:agent"* ]]
+  # Full SCOPE block is NOT re-emitted.
+  [[ "$output" != *"Does NOT apply to"* ]]
+}
+
+@test "architect-detect: terse reminder preserves the MANDATORY signal word" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  # Per JTBD-lead condition: terse reminder must keep an imperative
+  # marker (MANDATORY / REQUIRED / NON-OPTIONAL) so the enforcement
+  # signal does not soften after turn 1.
+  [[ "$output" == *"MANDATORY"* ]] || [[ "$output" == *"REQUIRED"* ]] || [[ "$output" == *"NON-OPTIONAL"* ]]
+}
+
+@test "architect-detect: terse reminder names the trigger artifact" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  # Per JTBD-lead condition: reason for the gate must stay visible
+  # on subsequent turns.
+  [[ "$output" == *"docs/decisions"* ]]
+}
+
+@test "architect-detect: different session_id re-emits the full block" {
+  run_hook "$SID" >/dev/null
+  local SID2="${SID}-alt"
+  run run_hook "$SID2"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 500 ]
+  [[ "$output" == *"MANDATORY ARCHITECTURE CHECK"* ]]
+  rm -f "/tmp/architect-announced-${SID2}"
+}
+
+@test "architect-detect: empty session_id emits the full block and writes no marker" {
+  run run_hook ""
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 500 ]
+  [[ "$output" == *"MANDATORY ARCHITECTURE CHECK"* ]]
+  [ ! -f "/tmp/architect-announced-" ]
+}
+
+@test "architect-detect: absent docs/decisions/ emits the no-decisions NOTE (unchanged by this ADR)" {
+  local NO_DECISIONS="$(mktemp -d)"
+  run bash -c "cd '$NO_DECISIONS' && echo '{\"session_id\":\"$SID\"}' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no docs/decisions/ directory"* ]]
+  [[ "$output" != *"MANDATORY ARCHITECTURE CHECK"* ]]
+  rm -rf "$NO_DECISIONS"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.4.1-preview.161",
+  "version": "0.5.0-preview.168",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"