@windyroad/architect 0.2.0

package/.claude-plugin/plugin.json

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

package/agents/agent.md

@@ -0,0 +1,219 @@
+---
+name: agent
+description: Architecture reviewer for structural and technology decisions. Use
+  before editing any project file. Reviews proposed changes against existing
+  decisions in docs/decisions/ and flags when new decisions should be
+  documented. Checks source code for compliance with documented decisions
+  (e.g. API patterns, dependency choices, state machine rules). Works even
+  when no decisions exist yet.
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+model: inherit
+---
+
+You are the Architect. You review proposed changes against the project's architectural decisions before any architecture-bearing file is edited. You are a reviewer, not an editor.
+
+## Your Role
+
+1. Read all existing decisions in `docs/decisions/` (glob for `*.md`, skip `README.md`). If `docs/decisions/` does not exist yet, that is fine. Proceed with the review noting that no prior decisions are recorded.
+2. Read the file(s) being edited to understand the current state and proposed change
+3. Review the proposed change against existing decisions (if any)
+4. Determine if the change requires a new decision to be documented
+5. Report: PASS if compliant, or list issues requiring attention
+
+## What You Check
+
+### Decision Staleness Check
+
+For each `accepted` decision in `docs/decisions/`:
+- If the decision's `first-released` field (or `date` field when `first-released` is absent) is older than 6 months, flag **[Stale Decision]** (advisory, does not affect PASS/FAIL)
+- If a `reassessment-date` field exists in frontmatter and has passed, flag **[Reassessment Overdue]** (advisory)
+- If the decision has a **Reassessment Criteria** section and the triggers described there appear to have been met based on the current codebase, flag **[Reassessment Triggered]** (advisory)
+
+These staleness flags are informational only. They do NOT cause an ISSUES FOUND verdict.
+
+### Existing Decision Compliance
+
+For each accepted or proposed decision in `docs/decisions/`:
+- Does the proposed change conflict with the decision's outcome?
+- Does it violate any constraints or consequences documented in the decision?
+- If it conflicts, is there a good reason (experimentation, supersession)?
+
+### Confirmation Criteria Compliance
+
+Many decisions include a **Confirmation** section that describes how to verify implementation compliance (e.g. "Client JS does not contain hardcoded API URLs beyond the entry point"). When reviewing new or changed code:
+
+1. Identify which decisions are relevant to the files being changed (by topic, not just by name)
+2. Read the **Confirmation** section of each relevant decision
+3. Check whether the proposed code satisfies or violates those criteria
+4. Flag violations as **[Confirmation Violation]** with a reference to the specific criterion
+
+This catches cases where code is *consistent* with a decision's intent but violates its *specific compliance rules*.
+
+### New Decision Detection
+
+Flag when a proposed change represents an undocumented decision:
+
+- **New dependency** in `package.json`: Is there an existing decision covering this technology choice? If not, a decision should be proposed.
+- **New configuration pattern**: Does a config file change introduce a pattern not covered by existing decisions?
+- **New CI/CD workflow or hook**: Does this change the development process in a way that should be documented?
+- **New script**: Does this introduce a new workflow step?
+- **Structural change**: Does this reorganize code in a way that affects how the team works?
+
+### When NOT to flag
+
+Do NOT flag:
+- **Temporary choices**: One-off implementation details
+- **Obvious choices**: Decisions with only one viable option
+- **Reversible choices**: Easy to change without significant impact
+- **Local choices**: Decisions that only affect a single component or file
+- **Version bumps**: Updating an existing dependency to a newer version (unless it's a major version with breaking changes)
+- **Bug fixes**: Fixing a config or script to work correctly
+
+### Decision Quality Review
+
+When a change includes a new or modified decision file in `docs/decisions/`:
+- Does it follow MADR 4.0 format with required sections?
+- Does the frontmatter have all required fields (status, date, decision-makers, consulted, informed)?
+- Does it list at least 2 considered options with pros/cons?
+- Does it include reassessment criteria?
+- If it supersedes another decision, is the old decision properly updated?
+
+## How to Report
+
+If the change is compliant and no new decision is needed:
+
+> **Architecture Review: PASS**
+> No conflicts with existing decisions. No new architectural decision required.
+
+If there are issues:
+
+> **Architecture Review: ISSUES FOUND**
+>
+> 1. **[Issue Type]** - File: `path`
+>    - **Issue**: What needs attention
+>    - **Existing Decision**: Reference to relevant decision (if applicable)
+>    - **Action**: What should happen (document new decision, update existing, etc.)
+>
+> 2. ...
+
+Issue types:
+- **[Decision Conflict]**: Change conflicts with an accepted/proposed decision
+- **[Undocumented Decision]**: Change represents an architectural choice not covered by any existing decision
+- **[Decision Format]**: A decision file doesn't follow MADR 4.0 format
+- **[Missing Supersession]**: A new decision should supersede an old one but doesn't
+- **[Confirmation Violation]**: New code violates a confirmation criterion of an existing decision
+
+## Verdict File
+
+After completing your review, you MUST write a verdict file so the hook system knows the outcome:
+
+- After **PASS**: `echo "PASS" > /tmp/architect-verdict`
+- After **ISSUES FOUND**: `echo "FAIL" > /tmp/architect-verdict`
+
+Advisory items (staleness flags) do NOT count as FAIL. Only write FAIL when there are actionable issues (Decision Conflict, Undocumented Decision, Decision Format, Missing Supersession, Confirmation Violation).
+
+You MUST NOT use Bash for anything other than writing the verdict file.
+
+## Constraints
+
+- You are read-only. You do not edit files (the only exception is writing the verdict file via Bash).
+- You review all project files: source code, configuration, CI workflows, hook scripts, build scripts, and decision files. The only exclusions are stylesheets, images, lockfiles, and font files.
+- If the change is purely cosmetic (comments, formatting, whitespace), report PASS.
+- Do not block changes that are clearly within the scope of an existing accepted decision.
+- When flagging undocumented decisions, be pragmatic. Not every code change needs a decision record. Focus on choices that affect how the team works, what dependencies the project carries, how APIs behave, or how code flows to production. A refactored function or a bug fix is not an architectural decision. A new API endpoint that skips an established pattern is.
+
+## Decision Management Process
+
+This section defines the full process for architectural decisions. It is embedded here so the architect agent is self-contained with no external file dependencies.
+
+### Core Principles
+
+**Innovation vs. Standardization Balance**: Decisions represent standards that provide consistency while allowing innovation. Focus on the health of the decision-making system, not rigid enforcement. Think of decision management as cultivation, not control.
+
+**Natural Evolution**:
+- Endorse through production validation: decisions move from `proposed` to `accepted` only after successful production implementation
+- Graceful deprecation: old decisions are deprecated (not deleted) when better alternatives emerge
+- No retroactive enforcement: accepted decisions apply to new implementations, not existing code
+- Experimentation encouraged: successful experiments can become new proposed decisions
+
+### Decision Statuses
+
+Statuses are reflected in the filename:
+
+- **`proposed`** (`NNN-title.proposed.md`): New decision awaiting production validation. Can be used in new implementations.
+- **`accepted`** (`NNN-title.accepted.md`): Validated through production use. Must be followed in new implementations.
+- **`rejected`** (`NNN-title.rejected.md`): Evaluated and determined not suitable. Preserved for institutional knowledge.
+- **`deprecated`** (`NNN-title.deprecated.md`): No longer recommended, being phased out without specific replacement.
+- **`superseded`** (`NNN-title.superseded.md`): Replaced by a newer decision. Updated with "Superseded by" note.
+
+Status transitions:
+```
+proposed -> accepted (after production validation)
+proposed -> rejected (after evaluation determines unsuitability)
+accepted -> deprecated (when phasing out without specific replacement)
+accepted -> superseded (when replaced by newer decision)
+deprecated -> superseded (when specific replacement identified)
+```
+
+### Decision File Format (MADR 4.0)
+
+Required frontmatter:
+```yaml
+---
+status: "proposed|accepted|rejected|deprecated|superseded"
+date: YYYY-MM-DD
+decision-makers: [list of makers]
+consulted: [list of consulted resources/people]
+informed: [list of informed parties]
+reassessment-date: YYYY-MM-DD  # optional: when this decision should be reviewed
+first-released: YYYY-MM-DD    # optional: date this decision first shipped to production
+accepted-date: YYYY-MM-DD     # optional: date this decision was promoted to accepted
+---
+```
+
+Required sections:
+1. **Title**: Succinct summary of the decision
+2. **Context and Problem Statement**: What problem does this solve?
+3. **Decision Drivers**: Factors influencing the decision
+4. **Considered Options**: All alternatives evaluated (minimum 2)
+5. **Decision Outcome**: Chosen option and why
+6. **Consequences**: Good, neutral, and bad outcomes
+7. **Confirmation**: How to verify implementation compliance
+8. **Pros and Cons of the Options**: Detailed comparison
+9. **Reassessment Criteria** (recommended): When to review this decision
+
+### File Naming Convention
+
+```
+NNN-decision-title-in-kebab-case.STATUS.md
+```
+
+Files live in `docs/decisions/`. If the directory does not exist, create it when the first decision is documented.
+
+### When to Create Decisions
+
+Create decisions for choices about:
+- Architecture: system structure, component organization, design patterns
+- Technology: languages, frameworks, libraries, tools
+- Process: development workflows, quality gates, deployment strategies
+- Standards: coding conventions, naming patterns, file organization
+- Infrastructure: hosting, databases, third-party services
+
+Do NOT create decisions for:
+- Temporary choices: one-off implementation details
+- Obvious choices: decisions with only one viable option
+- Reversible choices: easy to change without significant impact
+- Local choices: decisions that only affect a single component or file
+
+### Superseding Process
+
+When decision NNN is superseded by decision MMM:
+1. Create new decision (MMM) with `supersedes: [NNN-old-decision-title]`
+2. Rename old decision file to `.superseded.md`
+3. Update old decision frontmatter status to `superseded`
+4. Add "Superseded by" section referencing the new decision
+5. Update `docs/decisions/README.md` if it exists

package/bin/install.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+
+const PLUGIN = "wr-architect";
+const DEPS = [];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/architect [options]
+
+Architecture decision enforcement for AI coding agents
+
+Options:
+  --update     Update this plugin and its skills
+  --uninstall  Remove this plugin
+  --dry-run    Show what would be done without executing
+  --help, -h   Show this help
+`);
+  process.exit(0);
+}
+
+if (flags.dryRun) {
+  utils.setDryRun(true);
+  console.log("[dry-run mode — no commands will be executed]\n");
+}
+
+utils.checkPrerequisites();
+
+if (flags.uninstall) {
+  utils.uninstallPackage(PLUGIN);
+} else if (flags.update) {
+  utils.updatePackage(PLUGIN);
+} else {
+  utils.installPackage(PLUGIN, { deps: DEPS });
+}

package/hooks/architect-detect.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Architecture - UserPromptSubmit hook
+# Detects docs/decisions/ directory and injects delegation instruction.
+# The architect agent reviews changes against architectural decision records.
+
+if [ -d "docs/decisions" ]; then
+  cat <<'HOOK_OUTPUT'
+INSTRUCTION: MANDATORY ARCHITECTURE CHECK. YOU MUST FOLLOW THIS.
+DETECTED: docs/decisions/ exists in this project.
+
+This is a NON-OPTIONAL instruction. You MUST use the architect agent
+before editing any project file. This includes source code, configuration,
+CI workflows, hook scripts, build scripts, and decision files. This is
+proactive. Do not wait for the user to ask.
+
+REQUIRED ACTIONS:
+1. Use the Agent tool to delegate to wr-architect:agent
+   (subagent_type: "wr-architect:agent")
+2. The architect will review proposed changes against existing decisions
+   in docs/decisions/ and flag when new decisions should be documented
+3. Do NOT edit project files without architect review FIRST
+4. Do NOT skip this step even if you think you can handle it yourself
+
+5. When in plan mode, review the plan file against existing decisions
+   in docs/decisions/ before calling ExitPlanMode
+
+6. Before proposing implementation options or alternatives to the user
+   (e.g., "Option A vs Option B", "where should this logic live?"),
+   consult the architect agent FIRST. Present only architect-approved
+   options. Do NOT present options that violate existing decisions.
+
+7. If the architect reports ISSUES FOUND, resolve the issues and
+   re-run the architect before editing. Do NOT proceed with edits
+   while issues are outstanding.
+
+SCOPE: All project files including source code, configs, CI, hooks,
+scripts, and decisions.
+Does NOT apply to: CSS/SCSS files, image assets, lockfiles, font files.
+HOOK_OUTPUT
+else
+  cat <<'HOOK_OUTPUT'
+NOTE: This project has no docs/decisions/ directory.
+If the user's task involves structural or technology decisions, consider
+asking whether they'd like to create an architecture decision record
+by delegating to wr-architect:agent.
+HOOK_OUTPUT
+fi

package/hooks/architect-enforce-edit.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Architecture - PreToolUse enforcement hook
+# BLOCKS Edit/Write to all project files until architect is consulted.
+# Excludes only non-architectural files: stylesheets, images, generated files.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/architect-gate.sh"
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  architect_gate_parse_error
+  exit 0
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only gate if the project has architecture decisions
+if [ ! -d "docs/decisions" ]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Exclude non-architectural files
+case "$FILE_PATH" in
+  *.css|*.scss|*.sass|*.less)
+    exit 0 ;;
+  *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.webp)
+    exit 0 ;;
+  *.woff|*.woff2|*.ttf|*.eot)
+    exit 0 ;;
+  *package-lock.json|*yarn.lock|*pnpm-lock.yaml)
+    exit 0 ;;
+  *.map)
+    exit 0 ;;
+  *.changeset/*.md|*/.changeset/*.md)
+    exit 0 ;;
+  */MEMORY.md|*/.claude/projects/*/memory/*)
+    exit 0 ;;
+  */.claude/plans/*.md|*.claude/plans/*.md)
+    exit 0 ;;
+  */RISK-POLICY.md)
+    exit 0 ;;
+  */.risk-reports/*)
+    exit 0 ;;
+  */docs/BRIEFING.md|docs/BRIEFING.md)
+    exit 0 ;;
+  */docs/problems/*.md|docs/problems/*.md)
+    exit 0 ;;
+esac
+
+# Check gate
+if check_architect_gate "$SESSION_ID"; then
+  exit 0
+fi
+
+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."
+  }
+}
+EOF
+exit 0

package/hooks/architect-mark-reviewed.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Architecture - PostToolUse hook for Agent tool
+# Creates a session marker when architect has been consulted.
+# This marker unlocks the architect-enforce-edit.sh PreToolUse block.
+# Mirrors: voice-tone-mark-reviewed.sh
+
+# Source shared portable helpers (_mtime, _hashcmd)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/gate-helpers.sh"
+
+INPUT=$(cat)
+
+SUBAGENT=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+case "$SUBAGENT" in
+  *architect*)
+    # Check verdict file from architect agent
+    VERDICT_FILE="/tmp/architect-verdict"
+    VERDICT=""
+    if [ -f "$VERDICT_FILE" ]; then
+      VERDICT=$(cat "$VERDICT_FILE")
+      rm -f "$VERDICT_FILE"
+    fi
+
+    case "$VERDICT" in
+      PASS)
+        # Architect explicitly passed, create marker
+        touch "/tmp/architect-reviewed-${SESSION_ID}"
+        ;;
+      FAIL)
+        # Architect found issues, do NOT create marker
+        ;;
+      *)
+        # No verdict file (agent error or old agent version)
+        # Allow with warning to avoid permanent lockout
+        touch "/tmp/architect-reviewed-${SESSION_ID}"
+        ;;
+    esac
+
+    # Store decision hash for drift detection
+    if [ -f "/tmp/architect-reviewed-${SESSION_ID}" ]; then
+      if [ -d "docs/decisions" ]; then
+        HASH=$(find docs/decisions -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+      else
+        HASH="none"
+      fi
+      echo "$HASH" > "/tmp/architect-reviewed-${SESSION_ID}.hash"
+    fi
+
+    ;;
+esac
+
+exit 0

package/hooks/architect-plan-enforce.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Architecture - PreToolUse enforcement hook for ExitPlanMode
+# BLOCKS ExitPlanMode until architect has reviewed the plan against ADRs.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/architect-gate.sh"
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  architect_gate_parse_error
+  exit 0
+fi
+
+# Only gate if the project has architecture decisions
+if [ ! -d "docs/decisions" ]; then
+  exit 0
+fi
+
+# Check gate
+if check_architect_gate "$SESSION_ID"; then
+  exit 0
+fi
+
+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."
+  }
+}
+EOF
+exit 0

package/hooks/architect-refresh-hash.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Architecture - PostToolUse hook for Edit/Write
+# Refreshes the stored decision hash after an allowed write to docs/decisions/.
+# This prevents drift detection from invalidating the marker when creating
+# new decision files that the architect just approved.
+
+# Portable hash: tries md5sum, falls back to md5 -r, then shasum
+_hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ] || [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only act on writes to docs/decisions/
+case "$FILE_PATH" in
+  */docs/decisions/*|docs/decisions/*)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+MARKER="/tmp/architect-reviewed-${SESSION_ID}"
+HASH_FILE="/tmp/architect-reviewed-${SESSION_ID}.hash"
+
+# Only refresh if a valid marker exists
+if [ -f "$MARKER" ] && [ -f "$HASH_FILE" ]; then
+  if [ -d "docs/decisions" ]; then
+    HASH=$(find docs/decisions -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+  else
+    HASH="none"
+  fi
+  echo "$HASH" > "$HASH_FILE"
+fi
+
+exit 0

package/hooks/architect-reset-marker.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Architecture - Stop hook
+# Removes the architect session marker so the next turn requires a fresh review.
+# Mirrors: voice-tone-reset-marker.sh
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -n "$SESSION_ID" ]; then
+  rm -f "/tmp/architect-reviewed-${SESSION_ID}"
+  rm -f "/tmp/architect-reviewed-${SESSION_ID}.hash"
+fi
+
+exit 0

package/hooks/hooks.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-detect.sh" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-enforce-edit.sh" }] },
+      { "matcher": "ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-plan-enforce.sh" }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-mark-reviewed.sh" }] },
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-refresh-hash.sh" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-reset-marker.sh" }] }
+    ]
+  }
+}

package/hooks/lib/architect-gate.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Shared gate logic for architect enforcement hooks.
+# Sourced by architect-enforce-edit.sh and architect-plan-enforce.sh.
+# Provides: check_architect_gate
+
+# Source shared portable helpers (_mtime, _hashcmd)
+_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).
+# Usage: check_architect_gate "$SESSION_ID"
+check_architect_gate() {
+  local SESSION_ID="$1"
+  local MARKER="/tmp/architect-reviewed-${SESSION_ID}"
+  local TTL_SECONDS="${ARCHITECT_TTL:-600}"
+
+  if [ -n "$SESSION_ID" ] && [ -f "$MARKER" ]; then
+    local NOW=$(date +%s)
+    local MARKER_TIME=$(_mtime "$MARKER")
+    local AGE=$(( NOW - MARKER_TIME ))
+    if [ "$AGE" -lt "$TTL_SECONDS" ]; then
+      # TTL still valid -- check for decision drift
+      local HASH_FILE="/tmp/architect-reviewed-${SESSION_ID}.hash"
+      if [ -f "$HASH_FILE" ]; then
+        local STORED=$(cat "$HASH_FILE")
+        local CURRENT
+        if [ -d "docs/decisions" ]; then
+          CURRENT=$(find docs/decisions -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+        else
+          CURRENT="none"
+        fi
+        if [ "$STORED" != "$CURRENT" ]; then
+          rm -f "$MARKER" "$HASH_FILE"
+          return 1  # Drift detected, deny
+        else
+          touch "$MARKER"  # Slide TTL window forward
+          return 0  # Valid, allow
+        fi
+      else
+        touch "$MARKER"  # Slide TTL window forward
+        return 0  # No hash = old marker format, allow
+      fi
+    else
+      rm -f "$MARKER"
+      return 1  # TTL expired, deny
+    fi
+  fi
+
+  return 1  # No marker, deny
+}
+
+# Emit fail-closed deny JSON for parse failures
+architect_gate_parse_error() {
+  cat <<'EOF'
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
+    "permissionDecisionReason": "BLOCKED: Could not parse hook input. Gate is fail-closed." } }
+EOF
+}

package/hooks/lib/gate-helpers.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# Shared portable helpers for gate enforcement hooks.
+# Sourced by architect-gate.sh, risk-gate.sh, and all hook scripts.
+# Provides: _mtime, _hashcmd, _doc_exclusions, _err_trap, _get_*
+
+# ---------------------------------------------------------------------------
+# Portable utilities
+# ---------------------------------------------------------------------------
+
+# Portable mtime: tries GNU stat, falls back to macOS stat
+_mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null || echo 0; }
+
+# Portable hash: tries md5sum, falls back to md5 -r, then shasum
+_hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
+
+# Paths excluded from pipeline state hashing and docs-only detection.
+_doc_exclusions() {
+    echo ':!docs/' ':!.risk-reports/' ':!.changeset/' ':!governance/' ':!.claude/plans/' ':!CLAUDE.md' ':!AGENTS.md' ':!PRINCIPLES.md' ':!DECISION-MANAGEMENT.md' ':!AGENTIC_RISK_REGISTER.md' ':!PROBLEM-MANAGEMENT.md'
+}
+
+# ---------------------------------------------------------------------------
+# ERR trap: outputs diagnostic JSON on hook errors (P010)
+# Usage: source gate-helpers.sh at top of hook, then call _enable_err_trap
+# ---------------------------------------------------------------------------
+
+_enable_err_trap() {
+    trap '_err_trap_handler "$BASH_SOURCE" "$LINENO" "$BASH_COMMAND"' ERR
+}
+
+_err_trap_handler() {
+    local script="$1" line="$2" cmd="$3"
+    local name
+    name=$(basename "$script" 2>/dev/null || echo "$script")
+    # Output diagnostic as systemMessage so it's visible in conversation
+    cat <<EOF
+{
+  "systemMessage": "Hook error in ${name} at line ${line}: ${cmd}"
+}
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# JSON input parsing: standardised helpers replacing inline python3
+# Each reads from _HOOK_INPUT (set by the hook before calling these)
+# ---------------------------------------------------------------------------
+
+# Store hook input for reuse by parsing helpers
+_HOOK_INPUT=""
+
+_parse_input() {
+    _HOOK_INPUT=$(cat)
+}
+
+_get_tool_name() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_session_id() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_command() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_file_path() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    ti = data.get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_subagent_type() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('subagent_type', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_user_prompt() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('user_prompt', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_tool_output() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    # PostToolUse provides tool_response (dict with content array), not tool_output
+    tr = data.get('tool_response', {})
+    if isinstance(tr, dict):
+        content = tr.get('content', [])
+        if isinstance(content, list):
+            texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
+            if texts:
+                print('\n'.join(texts))
+                sys.exit(0)
+    # Fallback for older/different hook formats
+    print(data.get('tool_output', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# Session-scoped tmp directory for risk files
+# ---------------------------------------------------------------------------
+
+# Returns the session-scoped directory for risk temp files.
+# Creates the directory if it doesn't exist.
+# Usage: DIR=$(_risk_dir "$SESSION_ID"); echo "1" > "$DIR/commit"
+_risk_dir() {
+  local sid="$1"
+  local dir="${TMPDIR:-/tmp}/claude-risk-${sid}"
+  mkdir -p "$dir"
+  echo "$dir"
+}
+
+# ---------------------------------------------------------------------------
+# Non-doc file detection for WIP gating
+# ---------------------------------------------------------------------------
+
+_is_doc_file() {
+    local file_path="$1"
+    local EXCL
+    EXCL=$(_doc_exclusions)
+    for pattern in $EXCL; do
+        local clean="${pattern#:!}"
+        case "$file_path" in
+            *"$clean"*) return 0 ;;
+        esac
+    done
+    case "$file_path" in
+        *.claude/*|*.risk-reports/*|*RISK-POLICY.md) return 0 ;;
+    esac
+    return 1
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@windyroad/architect",
+  "version": "0.2.0",
+  "description": "Architecture decision enforcement for AI coding agents",
+  "bin": {
+    "windyroad-architect": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/architect"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding"
+  ],
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/"
+  ]
+}

package/skills/wr:adr/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: wr:adr
+description: Create a new Architecture Decision Record (MADR 4.0) in docs/decisions/. Examines existing decisions, asks about the problem and options, and writes a properly formatted ADR.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Architecture Decision Record Generator
+
+Create a new ADR in `docs/decisions/` following MADR 4.0 format. The wr-architect:agent reviews these files to enforce architectural compliance.
+
+## Steps
+
+### 1. Discover existing decisions
+
+Scan for existing ADRs:
+- Glob `docs/decisions/*.md` (skip `README.md`)
+- Note the highest numbered decision to determine the next sequence number
+- Read any decisions related to the topic being discussed (if the user has mentioned a topic)
+- If `docs/decisions/` does not exist, create it
+
+### 2. Gather context from the user
+
+You MUST use the AskUserQuestion tool to collect the decision context. Do not proceed to step 3 until you have answers.
+
+Ask the user:
+
+1. **What is the decision about?** A brief title and the problem being solved.
+2. **What options were considered?** At least 2 alternatives (including "do nothing" if applicable). For each option, ask for key pros and cons.
+3. **What was chosen and why?** The selected option and the primary reason.
+4. **Who are the decision-makers?** Who made or is making this decision.
+5. **Any consequences to note?** Known good, neutral, or bad outcomes.
+
+If the user has already provided this context in the conversation (e.g., as arguments), use what they've given and only ask about what's missing.
+
+### 3. Determine sequence number and filename
+
+- Next number = highest existing decision number + 1 (or 001 if none exist)
+- Filename: `NNN-decision-title-in-kebab-case.proposed.md`
+- Pad the number to 3 digits (001, 002, ... 010, 011, etc.)
+
+### 4. Write the ADR
+
+Write the file to `docs/decisions/` with this structure:
+
+```markdown
+---
+status: "proposed"
+date: YYYY-MM-DD
+decision-makers: [from user input]
+consulted: [from user input, or empty list]
+informed: [from user input, or empty list]
+reassessment-date: YYYY-MM-DD  # 3 months from today
+---
+
+# Title
+
+## Context and Problem Statement
+
+[What problem does this solve? Why is a decision needed now?]
+
+## Decision Drivers
+
+- [Key factors influencing the decision]
+
+## Considered Options
+
+1. **Option A** - Brief description
+2. **Option B** - Brief description
+
+## Decision Outcome
+
+Chosen option: **"Option X"**, because [primary justification].
+
+## Consequences
+
+### Good
+
+- [Positive outcomes]
+
+### Neutral
+
+- [Trade-offs that are neither clearly good nor bad]
+
+### Bad
+
+- [Negative outcomes or risks accepted]
+
+## Confirmation
+
+[How to verify implementation compliance. Concrete, testable criteria.]
+
+## Pros and Cons of the Options
+
+### Option A
+
+- Good: [advantage]
+- Bad: [disadvantage]
+
+### Option B
+
+- Good: [advantage]
+- Bad: [disadvantage]
+
+## Reassessment Criteria
+
+[When should this decision be revisited? What conditions would trigger a review?]
+```
+
+Use today's date for the `date` field. Set `reassessment-date` to 3 months from today unless the user specifies otherwise.
+
+### 5. Confirm with the user
+
+Present the written ADR and use AskUserQuestion to ask:
+1. Does the problem statement accurately capture the situation?
+2. Are the pros/cons fair and complete?
+3. Are the confirmation criteria testable?
+4. Should anyone else be listed as consulted or informed?
+
+Apply any feedback by editing the file.
+
+### 6. Handle supersession (if applicable)
+
+If the user mentions this decision replaces an existing one:
+1. Add `supersedes: [NNN-old-decision-title]` to the new decision's frontmatter
+2. Rename the old decision file from `.accepted.md` (or `.proposed.md`) to `.superseded.md`
+3. Update the old decision's frontmatter status to `superseded`
+4. Add a "Superseded by" section to the old decision referencing the new one
+
+$ARGUMENTS