@windyroad/architect 0.17.1 → 0.17.3

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.17.1"
+  "version": "0.17.3"
 }

package/hooks/architect-compendium-update-entry.sh

@@ -169,10 +169,22 @@ if [ -z "$new_entry" ] || ! printf '%s' "$new_entry" | grep -qE '^### ADR-[0-9]+
     exit 0
 fi
 
+# --- Capture pre-modification invariants for the fail-closed guard (P367) ---
+# A single-entry re-author must change ONLY the edited ADR's entry. Snapshot the
+# set of all ADR ids and the count of `## ` section headers, plus a backup of
+# the whole file, so the post-condition guard below can detect (and reject) any
+# silent tail truncation or spurious-id/section injection from the subprocess.
+before_ids=$(grep -oE '^### ADR-[0-9]+' "$readme" | grep -oE '[0-9]+' | sed 's/^0*//' | sort -n -u)
+before_sections=$(grep -cE '^## ' "$readme")
+entry_existed=0
+[ -n "$current_entry" ] && entry_existed=1
+
 # --- Apply the entry: delete any existing block, then insert sorted ---------
 tmp_entry=$(mktemp -t architect-entry.XXXXXX)
 tmp_readme=$(mktemp -t architect-readme.XXXXXX)
-trap 'rm -f "$tmp_entry" "$tmp_readme"' EXIT
+backup_readme=$(mktemp -t architect-readme-orig.XXXXXX)
+trap 'rm -f "$tmp_entry" "$tmp_readme" "$backup_readme"' EXIT
+cp "$readme" "$backup_readme"
 printf '%s\n' "$new_entry" > "$tmp_entry"
 
 # Pass 1 — remove any existing block for this ADR-ID (and the single blank line
@@ -218,6 +230,26 @@ awk -v id="$adr_id" -v section="$target_section" -v entryfile="$tmp_entry" '
     END { if (!done) { print ""; print entry } }
 ' "$tmp_readme" > "$readme"
 
+# --- Fail-closed post-condition guard (P367, ADR-078 criterion l) -----------
+# The rewrite must preserve every OTHER ADR's entry and the section structure;
+# only the edited ADR's entry may change (it may be newly added). If the result
+# dropped a pre-existing entry (silent tail truncation) or injected spurious ids
+# or sections (malformed subprocess emit), restore the original and degrade —
+# never stage a corrupted compendium. Same contract as the subprocess-failure
+# path: exit 0, do not block the body edit; Story B's pairing check surfaces it.
+after_ids=$(grep -oE '^### ADR-[0-9]+' "$readme" | grep -oE '[0-9]+' | sed 's/^0*//' | sort -n -u)
+after_sections=$(grep -cE '^## ' "$readme")
+expected_ids="$before_ids"
+if [ "$entry_existed" -eq 0 ]; then
+    expected_ids=$(printf '%s\n%s\n' "$before_ids" "$adr_id" | sed '/^$/d' | sort -n -u)
+fi
+edited_count=$(grep -oE '^### ADR-[0-9]+' "$readme" | grep -oE '[0-9]+' | sed 's/^0*//' | grep -cxF "$adr_id")
+if [ "$after_ids" != "$expected_ids" ] || [ "$after_sections" != "$before_sections" ] || [ "$edited_count" -ne 1 ]; then
+    cp "$backup_readme" "$readme"
+    echo "architect-compendium-update-entry: post-condition guard tripped for ADR-${adr_id} (compendium entry-set or section drift — possible truncation or spurious injection); restored README unchanged (degraded mode), not staged. Recover with wr-architect-generate-decisions-compendium && git add docs/decisions/README.md" >&2
+    exit 0
+fi
+
 # Stage the compendium so it lands in the same commit as the ADR body change.
 ( cd "$project_dir" && git add docs/decisions/README.md 2>/dev/null ) || \
     echo "architect-compendium-update-entry: git add docs/decisions/README.md failed (not a git repo or staging error) — stage it manually before commit" >&2

package/hooks/architect-readme-pairing-check.sh

@@ -31,6 +31,10 @@
 
 set -uo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/command-detect.sh
+source "$SCRIPT_DIR/lib/command-detect.sh"
+
 # PreToolUse input arrives on stdin as JSON.
 input=$(cat)
 
@@ -40,20 +44,15 @@ tool_name=$(printf '%s' "$input" | jq -r '.tool_name // ""' 2>/dev/null)
 command=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null)
 [ -n "$command" ] || exit 0
 
-# Only fire on `git commit` invocations. Leading-executable check (P268
-# pattern): a bare substring match would catch unrelated commands that mention
-# "git commit" (grep/sed/cat). Strip leading whitespace + env assignments, then
-# require the first effective tokens to be `git commit`.
-echo "$command" | awk '
-    {
-        sub(/^[[:space:]]+/, "")
-        while ($0 ~ /^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+/) {
-            sub(/^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+/, "")
-        }
-        if ($0 ~ /^git[[:space:]]+commit([[:space:]]|$)/) exit 0
-        exit 1
-    }
-' || exit 0
+# Only fire on `git commit` invocations. Delegates to the shared
+# command_invokes_git_commit helper (P268 family; synced from
+# packages/shared/hooks/lib/command-detect.sh per ADR-017) rather than
+# re-implementing leading-token detection inline — a bare substring match would
+# catch unrelated commands that mention "git commit" (grep/sed/cat), and an
+# inline awk re-implementation risks re-introducing the BSD/GNU portability bugs
+# (P366 `\b`) and prefix-stripping gaps (`cd <path> &&`) the helper already
+# solved and regression-tests.
+command_invokes_git_commit "$command" || exit 0
 
 # Allow-list bypass token (parity with the retired refresh-discipline hook and
 # ADR-014 commit-message bypass shape).

package/hooks/lib/command-detect.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# P268: shared command-detection helper for PreToolUse:Bash hooks
+# that need to distinguish ACTUAL `git commit` invocations from Bash
+# commands that merely MENTION the literal phrase "git commit" in
+# argument vectors or heredoc bodies (grep patterns, sed patterns,
+# echo strings, cat heredocs, `git log --grep` queries, etc.).
+#
+# Replaces the case-statement substring match
+#
+#     case "$COMMAND" in
+#       *"git commit"*) ;;
+#       *) exit 0 ;;
+#     esac
+#
+# that 5 sibling PreToolUse:Bash hooks previously used to gate on
+# `git commit`. The substring match misfired on legitimate non-commit
+# Bash whose arguments contained the phrase (P268 ticket Description
+# — observed iter-1 retro write and orchestrator grep, ≥3 events per
+# session).
+#
+# Strategy (Fix shape B per P268 ticket):
+#   1. Strip leading whitespace from the candidate command string.
+#   2. Iteratively strip env-var-assignment prefixes (`VAR=value `,
+#      `VAR="..." `, `VAR='...' `) and a `cd <path> &&` prefix until
+#      stable (order-independent — both shapes can interleave).
+#   3. Check whether the residual leading token pair is literally
+#      `git[whitespace]commit` followed by whitespace or end-of-
+#      string. The end-of-token boundary check stops `git commit-tree`
+#      and similar `git commit-*` plumbing commands from matching.
+#
+# Scope deliberately narrow (per P268 ticket Description recommended
+# Fix shape B): handles only the prefix shapes the orchestrator and
+# capture/manage/work skills actually emit — direct `git commit`,
+# `cd && git commit`, `VAR=value git commit`. Does NOT split on
+# `&&`/`||`/`;`/`|` mid-chain — so `git add foo && git commit` reads
+# as `git add` leading and the helper returns 1 (the gate silently
+# passes). That is a documented and acceptable false-negative: a
+# stand-alone re-run of `git commit` re-triggers detection. False
+# positives — the case this fix exists to close — were causing the
+# orchestrator to need manual workaround (stage README first, then
+# run the offending non-commit command) 3+ times per session.
+#
+# Pure exit-code contract — helper never writes to stdout or stderr.
+# Callers that need to name the trigger surface in deny messages
+# should do so from their own delegated-detect helpers (e.g.
+# `lib/readme-refresh-detect.sh` echoes the offending ticket path).
+#
+# References:
+#   ADR-005  — plugin testing strategy (this helper's bats live at
+#              `packages/itil/hooks/test/command-detect.bats` per
+#              behavioural-test discipline).
+#   ADR-009  — gate marker lifecycle (helper is per-invocation, no
+#              marker state — same precedent as `lib/staging-detect.sh`,
+#              `lib/changeset-detect.sh`, `lib/readme-refresh-detect.sh`).
+#   ADR-045  — hook injection budget (silent-on-pass / silent-on-fail
+#              — pure exit-code contract).
+#   P125     — sibling staging-trap hook (candidate for follow-up
+#              refactor to use this helper).
+#   P141     — sibling changeset-discipline hook (candidate).
+#   P165     — sibling README-refresh-discipline hook (first consumer
+#              under P268).
+#   P268     — this helper's surfacing ticket.
+
+# Returns 0 if $1 is a Bash command that invokes `git commit`.
+# Returns 1 otherwise (including commands that merely mention the
+# phrase in their argument vectors or heredoc bodies, and commands
+# whose leading-effective token is some other git subcommand).
+command_invokes_git_commit() {
+  local cmd="$1"
+
+  # Strip leading whitespace (spaces, tabs, newlines).
+  if [[ "$cmd" =~ ^[[:space:]]+ ]]; then
+    cmd="${cmd#"${BASH_REMATCH[0]}"}"
+  fi
+
+  # Iteratively strip env-var-assignment prefixes and `cd <path> &&`
+  # prefixes until stable. The order is unconstrained: both shapes
+  # can appear in either sequence (`VAR=1 cd /tmp && git commit` or
+  # `cd /tmp && VAR=1 git commit`).
+  local prev=""
+  while [ "$cmd" != "$prev" ]; do
+    prev="$cmd"
+
+    # Env-var assignment with double-quoted value: VAR="..." then ws.
+    if [[ "$cmd" =~ ^[A-Za-z_][A-Za-z0-9_]*=\"[^\"]*\"[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    # Env-var assignment with single-quoted value: VAR='...' then ws.
+    if [[ "$cmd" =~ ^[A-Za-z_][A-Za-z0-9_]*=\'[^\']*\'[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    # Env-var assignment with unquoted value: VAR=word then ws.
+    # `word` here is any sequence of non-whitespace characters.
+    if [[ "$cmd" =~ ^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    # `cd <path> &&` prefix. Path token is double-quoted, single-
+    # quoted, or unquoted (in which case it cannot itself contain
+    # whitespace or `&`).
+    if [[ "$cmd" =~ ^cd[[:space:]]+\"[^\"]*\"[[:space:]]*\&\&[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    if [[ "$cmd" =~ ^cd[[:space:]]+\'[^\']*\'[[:space:]]*\&\&[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    if [[ "$cmd" =~ ^cd[[:space:]]+[^[:space:]\&]+[[:space:]]*\&\&[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+  done
+
+  # After prefix-strip, the leading two tokens must be literally
+  # `git` and `commit`, with whitespace or end-of-string after
+  # `commit` (so `git commit-tree` and similar do not match).
+  [[ "$cmd" =~ ^git[[:space:]]+commit([[:space:]]|$) ]]
+}

package/hooks/test/architect-compendium-update-entry.bats

@@ -234,6 +234,64 @@ run_hook() {
   [ "$status" -eq 0 ]
 }
 
+@test "fail-closed guard: rejects a subprocess entry that injects spurious ADR ids/sections — restores README, degraded, unstaged (P367)" {
+  mk_readme
+  ( cd "$PROJ" && git add -A && git commit -q -m init )
+  before=$(cat "$PROJ/docs/decisions/README.md")
+  fp=$(mk_adr "049" "accepted" "FortyNine")
+  # Malformed shim: valid header for the edited id, but ALSO injects an
+  # unrelated ADR-999 header and a spurious '## ' section — the additive
+  # corruption shape empirically reproduced for P367.
+  BADDIR="$(mktemp -d)"
+  cat > "$BADDIR/claude" <<'SHIM'
+#!/usr/bin/env bash
+cat >/dev/null
+entry="### ADR-049 — Hijacked
+**Status:** accepted | **Oversight:** confirmed
+**Decides:** body.
+
+## Injected section
+
+### ADR-999 — Sneaky"
+jq -cn --arg r "$entry" '{result:$r}'
+SHIM
+  chmod +x "$BADDIR/claude"
+  export PATH="$BADDIR:$ORIG_PATH"
+  run run_hook "$fp"
+  [ "$status" -eq 0 ]                                          # never blocks the body edit
+  [ "$before" = "$(cat "$PROJ/docs/decisions/README.md")" ]    # restored unchanged
+  ! grep -q 'ADR-999' "$PROJ/docs/decisions/README.md"         # no injected id survives
+  [[ "$output" == *"guard"* ]]                                 # observable degraded signal
+  # README left in its committed state — no corrupted blob staged.
+  ( cd "$PROJ" && git diff --cached --quiet -- docs/decisions/README.md )
+  rm -rf "$BADDIR"
+}
+
+@test "fail-closed guard: rejects an emit for the wrong ADR id (edited id absent) — restores, degraded (P367)" {
+  mk_readme
+  before=$(cat "$PROJ/docs/decisions/README.md")
+  fp=$(mk_adr "050" "proposed" "Fifty")          # NEW adr — not yet in the compendium
+  # Shim emits an entry for the WRONG id (049, which already exists) instead of
+  # the edited 050: the edited id never lands and 049 is duplicated.
+  WRONGDIR="$(mktemp -d)"
+  cat > "$WRONGDIR/claude" <<'SHIM'
+#!/usr/bin/env bash
+cat >/dev/null
+entry="### ADR-049 — WrongId
+**Status:** proposed | **Oversight:** confirmed
+**Decides:** body."
+jq -cn --arg r "$entry" '{result:$r}'
+SHIM
+  chmod +x "$WRONGDIR/claude"
+  export PATH="$WRONGDIR:$ORIG_PATH"
+  run run_hook "$fp"
+  [ "$status" -eq 0 ]
+  [ "$before" = "$(cat "$PROJ/docs/decisions/README.md")" ]    # restored unchanged
+  ! grep -q '^### ADR-050' "$PROJ/docs/decisions/README.md"    # edited id never landed
+  [[ "$output" == *"guard"* ]]
+  rm -rf "$WRONGDIR"
+}
+
 @test "registered in hooks.json on PostToolUse Edit|Write (criterion 9)" {
   HOOKS_JSON="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/hooks.json"
   run jq -e '.hooks.PostToolUse[] | select(.matcher | test("Edit")) | .hooks[] | select(.command | test("architect-compendium-update-entry"))' "$HOOKS_JSON"

package/hooks/test/architect-readme-pairing-check.bats

@@ -83,6 +83,42 @@ run_commit_hook() {
   [ "$status" -eq 0 ]
 }
 
+# --- P366 leading-token detection regression guards ---
+# These exercise the shared command_invokes_git_commit helper that the hook
+# now sources (replacing inline awk). Permit-path-only coverage is what let
+# the original BSD-awk `\b` bug hide; these are the deny-path / mention-path
+# guards the ticket asks for.
+
+@test "denies 'cd <repo> && git commit' with an unpaired ADR (P366 cd-prefix)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook "cd $REPO && git commit -m wip"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"deny"* ]]
+}
+
+@test "denies 'VAR=1 git commit' with an unpaired ADR (P366 env-prefix)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook "GIT_AUTHOR_NAME=x git commit -m wip"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"deny"* ]]
+}
+
+@test "permits a command that merely MENTIONS 'git commit' as a substring (P366 mention-path)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook "grep -r 'git commit' docs/"
+  [ "$status" -eq 0 ]
+}
+
+@test "permits 'git commit-tree' plumbing (P366 token-boundary)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook "git commit-tree HEAD"
+  [ "$status" -eq 0 ]
+}
+
 @test "registered in hooks.json as PreToolUse Bash (criterion 6)" {
   HOOKS_JSON="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/hooks.json"
   run jq -e '.hooks.PreToolUse[] | select(.matcher=="Bash") | .hooks[] | select(.command | test("architect-readme-pairing-check"))' "$HOOKS_JSON"

package/package.json

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