@windyroad/architect 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,65 @@
+# @windyroad/architect
+
+**Architecture decision enforcement for Claude Code.** Ensures every code change is reviewed against your project's architecture decisions before it lands.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+The architect plugin prevents architectural drift by gating edits behind an architecture review. When you have a `docs/decisions/` directory, the plugin:
+
+1. **Detects** your architecture decisions on every prompt
+2. **Blocks** edits to project files until the architect agent has reviewed the proposed changes
+3. **Reviews** changes against your existing ADRs (Architecture Decision Records) and flags conflicts
+4. **Flags** when a new decision should be documented
+
+No decisions directory yet? The plugin stays silent until you create one.
+
+## Install
+
+```bash
+npx @windyroad/architect
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+Once installed, the plugin works automatically. You don't need to invoke it -- it intercepts edits and runs the review before allowing changes through.
+
+**Create a new Architecture Decision Record:**
+
+```
+/wr-architect:create-adr
+```
+
+This walks you through creating an ADR in [MADR 4.0](https://adr.github.io/madr/) format. It examines your existing decisions, asks about the problem and options, and writes a properly formatted record to `docs/decisions/`.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `architect-detect.sh` | Every prompt | Checks for `docs/decisions/` and injects the review instruction |
+| `architect-enforce-edit.sh` | Edit or Write | Blocks the edit if the architect hasn't reviewed yet |
+| `architect-plan-enforce.sh` | ExitPlanMode | Ensures plans are reviewed before execution |
+| `architect-mark-reviewed.sh` | Agent completes | Marks the review as done (TTL: 1800s) |
+| `architect-refresh-hash.sh` | After edit | Refreshes the content hash so the next edit triggers a fresh review |
+
+## Agent
+
+The `wr-architect:agent` reviews proposed changes against existing decisions in `docs/decisions/` and reports:
+
+- Whether changes comply with or violate existing decisions
+- Whether a new ADR should be created
+- Whether existing decisions are stale and need reassessment
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/architect --update
+npx @windyroad/architect --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/agents/agent.md

@@ -10,7 +10,6 @@ tools:
   - Read
   - Glob
   - Grep
-  - Bash
 model: inherit
 ---
 
@@ -107,20 +106,9 @@ Issue types:
 - **[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 are read-only. You do not edit files.
 - 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.

package/bin/install.mjs

@@ -4,7 +4,7 @@ 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 utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
 
 const PLUGIN = "wr-architect";
 const DEPS = [];
@@ -20,6 +20,7 @@ Architecture decision enforcement for AI coding agents
 Options:
   --update     Update this plugin and its skills
   --uninstall  Remove this plugin
+  --scope      Installation scope: project (default) or user
   --dry-run    Show what would be done without executing
   --help, -h   Show this help
 `);
@@ -38,5 +39,5 @@ if (flags.uninstall) {
 } else if (flags.update) {
   utils.updatePackage(PLUGIN);
 } else {
-  utils.installPackage(PLUGIN, { deps: DEPS });
+  utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
 }

package/hooks/architect-enforce-edit.sh

@@ -20,6 +20,17 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
+# P004: Only gate files inside the project root. Absolute paths outside
+# $PWD (e.g., ~/.claude/channels/*) are not project files.
+case "$FILE_PATH" in
+  /*)
+    case "$FILE_PATH" in
+      "$PWD"/*) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
 # Only gate if the project has architecture decisions
 if [ ! -d "docs/decisions" ]; then
   exit 0
@@ -53,6 +64,17 @@ case "$FILE_PATH" in
     exit 0 ;;
   */docs/problems/*.md|docs/problems/*.md)
     exit 0 ;;
+  # Peer-plugin policy files — governed by their own plugin's enforce hook, not architect (P009)
+  */docs/JOBS_TO_BE_DONE.md|docs/JOBS_TO_BE_DONE.md)
+    exit 0 ;;
+  */docs/PRODUCT_DISCOVERY.md|docs/PRODUCT_DISCOVERY.md)
+    exit 0 ;;
+  */docs/jtbd/*|docs/jtbd/*)
+    exit 0 ;;
+  */docs/VOICE-AND-TONE.md|docs/VOICE-AND-TONE.md)
+    exit 0 ;;
+  */docs/STYLE-GUIDE.md|docs/STYLE-GUIDE.md)
+    exit 0 ;;
 esac
 
 # Check gate

package/hooks/architect-mark-reviewed.sh

@@ -1,17 +1,19 @@
 #!/bin/bash
 # Architecture - PostToolUse hook for Agent tool
 # Creates a session marker when architect has been consulted.
+# Parses verdict from agent output text (session-safe, no temp files).
 # 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)
+_parse_input
 
-SUBAGENT=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty') || true
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+TOOL_NAME=$(_get_tool_name)
+[ "$TOOL_NAME" = "Agent" ] || exit 0
+
+SUBAGENT=$(_get_subagent_type)
+SESSION_ID=$(_get_session_id)
 
 if [ -z "$SESSION_ID" ]; then
   exit 0
@@ -19,25 +21,24 @@ fi
 
 case "$SUBAGENT" in
   *architect*)
-    # Check verdict file from architect agent
-    VERDICT_FILE="/tmp/architect-verdict"
+    # Parse verdict from agent output text (no temp file needed)
+    AGENT_OUTPUT=$(_get_tool_output)
     VERDICT=""
-    if [ -f "$VERDICT_FILE" ]; then
-      VERDICT=$(cat "$VERDICT_FILE")
-      rm -f "$VERDICT_FILE"
+    if echo "$AGENT_OUTPUT" | grep -q "Architecture Review: PASS"; then
+      VERDICT="PASS"
+    elif echo "$AGENT_OUTPUT" | grep -q "ISSUES FOUND"; then
+      VERDICT="FAIL"
     fi
 
     case "$VERDICT" in
       PASS)
-        # Architect explicitly passed, create marker
         touch "/tmp/architect-reviewed-${SESSION_ID}"
         ;;
       FAIL)
-        # Architect found issues, do NOT create marker
+        # Do NOT create marker — review found issues
         ;;
       *)
-        # No verdict file (agent error or old agent version)
-        # Allow with warning to avoid permanent lockout
+        # Could not parse verdict — allow with marker to avoid lockout
         touch "/tmp/architect-reviewed-${SESSION_ID}"
         ;;
     esac
@@ -52,6 +53,8 @@ case "$SUBAGENT" in
       echo "$HASH" > "/tmp/architect-reviewed-${SESSION_ID}.hash"
     fi
 
+    # Plan review marker
+    touch "/tmp/architect-plan-reviewed-${SESSION_ID}"
     ;;
 esac
 

package/hooks/hooks.json

@@ -10,9 +10,6 @@
     "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

@@ -12,7 +12,7 @@ source "$_ARCHITECT_GATE_DIR/gate-helpers.sh"
 check_architect_gate() {
   local SESSION_ID="$1"
   local MARKER="/tmp/architect-reviewed-${SESSION_ID}"
-  local TTL_SECONDS="${ARCHITECT_TTL:-600}"
+  local TTL_SECONDS="${ARCHITECT_TTL:-1800}"
 
   if [ -n "$SESSION_ID" ] && [ -f "$MARKER" ]; then
     local NOW=$(date +%s)

package/hooks/test/architect-enforce-scope.bats

@@ -0,0 +1,62 @@
+#!/usr/bin/env bats
+
+# Tests for architect-enforce-edit.sh — verifies peer-plugin policy files are
+# exempt from the architect gate (P009). Each plugin governs its own policy
+# docs via its own enforce hook; the architect should not re-gate them.
+#
+# All tests are functional (P011): they execute the hook with mock JSON
+# input and assert on exit status + BLOCKED output. Source-grep assertions
+# were removed because they over-specified the implementation and gave
+# false confidence (a literal string can appear in source without the
+# matching case branch actually short-circuiting).
+
+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 gate: architect-enforce only runs when docs/decisions/ exists.
+  mkdir -p docs/decisions
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+# Helper: run the hook with a mock JSON input for a given file path.
+# Claude Code passes absolute file_path values, so tests use $PWD-prefixed
+# paths to match real shape (after the P004 root check).
+run_hook_with_file() {
+  local file_path="$1"
+  local json="{\"tool_input\":{\"file_path\":\"${file_path}\"},\"session_id\":\"test-session-$$\"}"
+  echo "$json" | bash "$HOOK"
+}
+
+assert_path_allowed() {
+  local file_path="$1"
+  run run_hook_with_file "$file_path"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "architect: exempts JTBD policy file (P009)" {
+  assert_path_allowed "$PWD/docs/JOBS_TO_BE_DONE.md"
+}
+
+@test "architect: exempts JTBD directory file (P009)" {
+  assert_path_allowed "$PWD/docs/jtbd/solo-developer/persona.md"
+}
+
+@test "architect: exempts PRODUCT_DISCOVERY.md (P009)" {
+  assert_path_allowed "$PWD/docs/PRODUCT_DISCOVERY.md"
+}
+
+@test "architect: exempts voice-tone policy file (P009)" {
+  assert_path_allowed "$PWD/docs/VOICE-AND-TONE.md"
+}
+
+@test "architect: exempts style-guide policy file (P009)" {
+  assert_path_allowed "$PWD/docs/STYLE-GUIDE.md"
+}

package/hooks/test/architect-gate.bats

@@ -0,0 +1,32 @@
+#!/usr/bin/env bats
+
+# Tests for architect-gate.sh (TTL, drift, marker)
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  source "$SCRIPT_DIR/lib/architect-gate.sh"
+  TEST_SESSION="test-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  rm -f "/tmp/architect-reviewed-${TEST_SESSION}"
+  rm -f "/tmp/architect-reviewed-${TEST_SESSION}.hash"
+}
+
+@test "gate denies when no marker exists" {
+  run check_architect_gate "$TEST_SESSION"
+  [ "$status" -ne 0 ]
+}
+
+@test "gate allows when marker exists and is fresh" {
+  touch "/tmp/architect-reviewed-${TEST_SESSION}"
+  run check_architect_gate "$TEST_SESSION"
+  [ "$status" -eq 0 ]
+}
+
+@test "gate denies when marker is expired" {
+  touch "/tmp/architect-reviewed-${TEST_SESSION}"
+  # Set TTL to 0 to force expiry
+  ARCHITECT_TTL=0 run check_architect_gate "$TEST_SESSION"
+  [ "$status" -ne 0 ]
+}

package/hooks/test/architect-mark-reviewed.bats

@@ -0,0 +1,26 @@
+#!/usr/bin/env bats
+
+# Tests for architect verdict parsing from output text
+
+@test "grep matches 'Architecture Review: PASS'" {
+  output="Some preamble text\n\n**Architecture Review: PASS**\n\nNo conflicts."
+  echo -e "$output" | grep -q "Architecture Review: PASS"
+}
+
+@test "grep matches 'ISSUES FOUND'" {
+  output="**Architecture Review: ISSUES FOUND**\n\n1. [Decision Conflict]"
+  echo -e "$output" | grep -q "ISSUES FOUND"
+}
+
+@test "grep does NOT match unrelated text" {
+  output="The review is complete. Everything looks good."
+  ! echo -e "$output" | grep -q "Architecture Review: PASS"
+}
+
+@test "subagent pattern matches wr-architect:agent" {
+  SUBAGENT="wr-architect:agent"
+  case "$SUBAGENT" in
+    *architect*) true ;;
+    *) false ;;
+  esac
+}

package/hooks/test/architect-no-stop-hook.bats

@@ -0,0 +1,17 @@
+#!/usr/bin/env bats
+
+# P001 / ADR-009: Stop-hook marker reset removed. Marker lifecycle is
+# governed by TTL + drift detection. This test asserts the Stop hook
+# entry is absent from the plugin's hooks.json.
+
+setup() {
+  PLUGIN_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
+}
+
+@test "architect: hooks.json has no Stop hook entry (ADR-009)" {
+  ! grep -q '"Stop"' "$PLUGIN_DIR/hooks/hooks.json"
+}
+
+@test "architect: architect-reset-marker.sh has been removed" {
+  [ ! -f "$PLUGIN_DIR/hooks/architect-reset-marker.sh" ]
+}

package/hooks/test/architect-project-root.bats

@@ -0,0 +1,44 @@
+#!/usr/bin/env bats
+
+# Tests for architect-enforce-edit.sh project-root check (P004).
+# Verifies that absolute paths outside $PWD are exempted.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/architect-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+}
+
+run_hook_with_file() {
+  local file_path="$1"
+  local json="{\"tool_input\":{\"file_path\":\"${file_path}\"},\"session_id\":\"test-session-$$\"}"
+  echo "$json" | bash "$HOOK"
+}
+
+@test "project-root: absolute path outside project exits 0" {
+  run run_hook_with_file "/Users/other/somewhere/file.json"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "project-root: home-dir config path exits 0" {
+  run run_hook_with_file "/Users/somebody/.claude/channels/discord/access.json"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "project-root: absolute path inside \$PWD is still gated" {
+  # Use a temp dir as PWD with docs/decisions to trigger the gate
+  TEST_DIR=$(mktemp -d)
+  mkdir -p "$TEST_DIR/docs/decisions"
+  echo "# ADR" > "$TEST_DIR/docs/decisions/001-test.proposed.md"
+  cd "$TEST_DIR"
+  run run_hook_with_file "$TEST_DIR/src/index.ts"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+  rm -rf "$TEST_DIR"
+}

package/lib/install-utils.mjs

@@ -0,0 +1,143 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName) {
+  return run(`claude plugin update ${pluginName}`, pluginName);
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+/**
+ * Install a single package: marketplace add + plugin install.
+ */
+export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName, { scope });
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName);
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+    scope: "project",
+  };
+  const scopeIdx = args.indexOf("--scope");
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const val = args[scopeIdx + 1];
+    if (["project", "user", "local"].includes(val)) {
+      flags.scope = val;
+    } else {
+      console.error("--scope requires: project, user, or local");
+      process.exit(1);
+    }
+  }
+  return flags;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "lib/"
   ]
 }

package/skills/{wr:adr → create-adr}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:adr
+name: wr-architect:create-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
 ---

package/skills/review-design/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: wr-architect:review-design
+description: On-demand architecture compliance review. Checks staged changes and recent commits against existing ADRs in docs/decisions/. Use before editing architecture-bearing files or before a release.
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion, Skill
+---
+
+# Architecture Compliance Review Skill
+
+Run an architecture compliance review on demand — outside the pre-tool-use hook gate. Reviews staged changes and recent commits against the project's ADRs in `docs/decisions/`.
+
+This skill is **read-only**. It does not commit, push, or modify files.
+
+## When to use
+
+- Pre-flight before a release or client handover: confirm no ADR violations crept in
+- After a large refactor: verify the new structure still complies with decisions
+- When proposing a structural change: get a review before editing architecture-bearing files
+- Any time the hook gate is not convenient: e.g., planning mode, exploratory spikes
+
+## Steps
+
+### 1. Parse arguments
+
+Read `$ARGUMENTS` for an explicit review scope (e.g., "review my changes to the auth module", "check the new API routes", "pre-release review"). If a scope is provided, use it. If empty, proceed to auto-detection.
+
+### 2. Auto-detect context
+
+Run the following to establish what needs reviewing:
+
+```bash
+# Staged changes
+git diff --cached --stat
+
+# Recent commits not yet pushed
+git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD --oneline 2>/dev/null || git log HEAD -5 --oneline
+
+# Changed files
+git diff --cached --name-only
+git diff --name-only HEAD
+```
+
+Summarise:
+- Files staged or recently committed
+- Whether the changes are architectural (source code, config, schema, tooling) vs purely documentary
+
+### 3. Resolve ambiguity
+
+If there are no staged changes and no recent unpushed commits, use `AskUserQuestion` to ask:
+
+> "I don't see any staged or unpushed changes. What would you like me to review?
+> (a) A specific set of files — please name them
+> (b) All changes since the last tag
+> (c) A planned change you'd like to describe
+> (d) Cancel"
+
+Do not ask if there is an obvious set of changed files.
+
+### 4. Construct the assessment prompt
+
+Build a self-contained prompt for the architect subagent that includes:
+- The list of changed/staged files
+- The git diff summary (stat output)
+- Any explicit scope from the user
+- The request: "Review these proposed changes against the project's ADRs. Flag any violations, gaps that need a new ADR, or compliance questions."
+
+### 5. Delegate to wr-architect:agent
+
+Invoke the architect subagent via the `Skill` tool:
+
+```
+subagent_type: wr-architect:agent
+prompt: <constructed review prompt from step 4>
+```
+
+Wait for the subagent to complete.
+
+### 6. Present results
+
+Present the full compliance report to the user. The architect subagent will report:
+- PASS: no violations found
+- FLAGGED: specific violations or compliance questions with ADR references
+- NEW ADR NEEDED: decisions that should be recorded before proceeding
+
+If violations are flagged, use `AskUserQuestion` to ask how the user wants to proceed:
+- (a) Address the violations before continuing
+- (b) Proceed with a documented exception
+- (c) Draft a new or amended ADR to legitimise the approach
+
+Do not make the decision unilaterally — per ADR-013 Rule 1, architectural risk decisions are the user's.
+
+$ARGUMENTS

package/hooks/architect-reset-marker.sh

@@ -1,15 +0,0 @@
-#!/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