@opengroundplan/core 0.1.1

package/registry/commands/tasks/command.yaml

@@ -0,0 +1,7 @@
+id: tasks
+kind: command
+name: Task Breakdown
+description: Turn an approved plan into an ordered specs/NNN-slug/tasks.md where every task names the files it touches.
+tags: [workflow, specs, planning, tasks]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, gemini-cli]
+requiresCapability: [slash-commands]

package/registry/commands/verify/command.md

@@ -0,0 +1,43 @@
+---
+description: Run the repo's declared build/test/lint commands and report a green or red verdict
+argument-hint: [build|typecheck|lint|test|all]  e.g.  test   (defaults to all)
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Verify: $ARGUMENTS
+
+Run what this repo declares as its verification commands and report the first real failure.
+
+## Steps
+
+1. Read `AGENTS.md` and take the agent-kit `commands.*` values — `build`, `test`, `lint`, plus `typecheck` when declared. **These strings are the only commands this command may run.** Never substitute a guessed command for a detected stack; a missing declaration is a finding, not a licence to improvise.
+
+2. No declaration for the requested step → stop and report:
+   ```
+   VERDICT: RED — no `commands.<step>` declared in AGENTS.md
+   ```
+
+3. Select the steps. `$ARGUMENTS` empty or `all` → build, typecheck, lint, test, in that order: cheapest signal first, so a syntax error does not cost a full test run. Otherwise run only the named step.
+
+4. Run each declared command verbatim from the repo root. Stop at the first non-zero exit — later steps run against a broken tree and their output is noise.
+
+5. On failure, extract the **first** error only: file, line, message. Do not paste the log. Do not summarize fifty cascading errors that share one cause; find the cause.
+
+6. Report back:
+   ```
+   build      <PASS|FAIL|SKIP> — <command>
+   typecheck  <PASS|FAIL|SKIP> — <command>
+   lint       <PASS|FAIL|SKIP> — <command>
+   test       <PASS|FAIL|SKIP> — <command>  (<n> passed, <n> failed)
+
+   FIRST FAILURE
+     <path>:<line>
+     <message>
+     Likely cause: <one line>
+
+   VERDICT: GREEN | RED
+   ```
+
+   `SKIP` means the step was not selected or not declared — say which. A skipped step is never reported as a pass.
+
+7. Do **not** auto-edit. Report findings only.

package/registry/commands/verify/command.yaml

@@ -0,0 +1,7 @@
+id: verify
+kind: command
+name: Verify
+description: Run the build/test/lint commands declared in AGENTS.md and report a green/red verdict with the first failure.
+tags: [quality, verification, read-only]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, gemini-cli]
+requiresCapability: [slash-commands]

package/registry/hooks/_lib/config.ps1

@@ -0,0 +1,116 @@
+# Shared config + payload helpers for registry hooks. Dot-source, never run directly.
+# Resolution order per key: env var -> repo config file -> defaults.json. One default table, one place.
+
+$ErrorActionPreference = 'Stop'
+
+$script:ForgeLibDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$script:ForgeDefaults = $null
+$script:ForgeRepoConfig = $null
+
+function Get-GroundplanDefaults {
+    if ($null -eq $script:ForgeDefaults) {
+        $script:ForgeDefaults = Get-Content (Join-Path $script:ForgeLibDir 'defaults.json') -Raw | ConvertFrom-Json
+    }
+    return $script:ForgeDefaults
+}
+
+# Env keys are GROUNDPLAN_HOOK_ + UPPER_SNAKE of the config key.
+function Get-GroundplanEnvName([string]$Key) {
+    return 'GROUNDPLAN_HOOK_' + (($Key -creplace '([a-z0-9])([A-Z])', '$1_$2').ToUpperInvariant())
+}
+
+function Get-GroundplanRepoConfig {
+    if ($null -ne $script:ForgeRepoConfig) { return $script:ForgeRepoConfig }
+
+    $defaults = Get-GroundplanDefaults
+    $path = [Environment]::GetEnvironmentVariable((Get-GroundplanEnvName 'configPath'))
+    if (-not $path) { $path = $defaults.configPath }
+
+    if (Test-Path $path) {
+        try { $script:ForgeRepoConfig = Get-Content $path -Raw | ConvertFrom-Json }
+        catch { [Console]::Error.WriteLine("groundplan-hooks: ignoring unreadable config '$path' — $($_.Exception.Message)") }
+    }
+    # Cache the miss too, so a absent config file is not re-probed per key.
+    if ($null -eq $script:ForgeRepoConfig) { $script:ForgeRepoConfig = [pscustomobject]@{} }
+    return $script:ForgeRepoConfig
+}
+
+function Get-GroundplanConfig {
+    param([Parameter(Mandatory)][string]$Key)
+
+    # Env wins; arrays come in as a comma-separated list because env vars are flat.
+    $envValue = [Environment]::GetEnvironmentVariable((Get-GroundplanEnvName $Key))
+    if ($envValue) {
+        $defaultForType = (Get-GroundplanDefaults).$Key
+        if ($defaultForType -is [System.Array]) {
+            return @($envValue -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+        }
+        if ($defaultForType -is [int] -or $defaultForType -is [long] -or $defaultForType -is [double]) { return [int]$envValue }
+        if ($defaultForType -is [bool]) { return [bool]::Parse($envValue) }
+        return $envValue
+    }
+
+    $repo = Get-GroundplanRepoConfig
+    if ($repo.PSObject.Properties.Name -contains $Key) { return $repo.$Key }
+
+    return (Get-GroundplanDefaults).$Key
+}
+
+function Read-GroundplanPayload {
+    $raw = [Console]::In.ReadToEnd()
+    if (-not $raw) { return $null }
+    try { return $raw | ConvertFrom-Json } catch { return $null }
+}
+
+# Tool params differ by tool; check every field that can carry a target path.
+function Get-GroundplanPayloadPath($Payload) {
+    if (-not $Payload) { return $null }
+    foreach ($field in 'file_path', 'path', 'notebook_path') {
+        $value = $Payload.tool_input.$field
+        if ($value) { return $value }
+    }
+    return $null
+}
+
+# Write and Edit carry the new text under different keys.
+function Get-GroundplanPayloadContent($Payload) {
+    if (-not $Payload) { return $null }
+    $parts = foreach ($field in 'content', 'new_string', 'new_source') {
+        if ($Payload.tool_input.$field) { $Payload.tool_input.$field }
+    }
+    if ($Payload.tool_input.edits) {
+        $parts += $Payload.tool_input.edits | ForEach-Object { $_.new_string }
+    }
+    if (-not $parts) { return $null }
+    return ($parts -join "`n")
+}
+
+function ConvertTo-GroundplanSlashPath([string]$Path) {
+    if (-not $Path) { return $null }
+    $norm = $Path -replace '\\', '/'
+    # Match repo-relative rules against an absolute path by trimming the repo root.
+    $root = (& git rev-parse --show-toplevel 2>$null)
+    if ($LASTEXITCODE -eq 0 -and $root) {
+        $root = ($root.Trim() -replace '\\', '/').TrimEnd('/')
+        if ($norm.StartsWith($root, [StringComparison]::OrdinalIgnoreCase)) {
+            $norm = $norm.Substring($root.Length).TrimStart('/')
+        }
+    }
+    return $norm
+}
+
+# CaseSensitive matches grep -P in the bash twin; leave it off for paths, on for token patterns.
+function Test-GroundplanAnyMatch([string]$Value, $Patterns, [switch]$CaseSensitive) {
+    if (-not $Value -or -not $Patterns) { return $false }
+    foreach ($p in $Patterns) {
+        if ($CaseSensitive) { if ($Value -cmatch $p) { return $true } }
+        elseif ($Value -match $p) { return $true }
+    }
+    return $false
+}
+
+# Exit 2 is the block signal; stderr is what the model reads back.
+function Deny-GroundplanTool([string]$Message) {
+    [Console]::Error.WriteLine($Message)
+    exit 2
+}

package/registry/hooks/_lib/config.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Shared config + payload helpers for registry hooks. Source, never execute.
+# Resolution order per key: env var -> repo config file -> defaults.json. Same table as config.ps1.
+
+GROUNDPLAN_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GROUNDPLAN_DEFAULTS_FILE="$GROUNDPLAN_LIB_DIR/defaults.json"
+
+# Three engines, because a hook that cannot read its payload is a hook that does not run.
+# jq is the fast path; node and python3 each have a stdlib-only equivalent beside this file.
+# Between them there is no realistic environment left without one, which is what lets the
+# security hooks below refuse rather than wave an operation through unchecked.
+if command -v jq >/dev/null 2>&1; then
+  GROUNDPLAN_JSON_ENGINE=jq
+elif command -v node >/dev/null 2>&1; then
+  GROUNDPLAN_JSON_ENGINE=node
+elif command -v python3 >/dev/null 2>&1; then
+  GROUNDPLAN_JSON_ENGINE=python3
+elif command -v python >/dev/null 2>&1 && python -c 'import sys; sys.exit(0 if sys.version_info[0] == 3 else 1)' 2>/dev/null; then
+  GROUNDPLAN_JSON_ENGINE=python
+else
+  GROUNDPLAN_JSON_ENGINE=none
+fi
+
+gp_json_unavailable() {
+  [ "$GROUNDPLAN_JSON_ENGINE" = none ] && return 0 || return 1
+}
+
+# Same check for a hook that enforces a security boundary. Stepping aside quietly is the wrong
+# answer there: the guard disappears while the repo still looks guarded. With jq, node and
+# python3 all probed, a machine with none of them is rare enough that refusing is the safe
+# default. GROUNDPLAN_HOOK_STRICT=0 is the deliberate opt-out for an environment that has no
+# JSON engine and accepts running unguarded.
+gp_security_unavailable() {
+  gp_json_unavailable || return 1
+
+  if [ "${GROUNDPLAN_HOOK_STRICT:-1}" != "0" ]; then
+    gp_deny "BLOCKED: $1 cannot run — no JSON engine found (tried jq, node, python3).
+
+It checks $2. It cannot verify this operation, so it is refusing rather than waving it through.
+
+Install any one of:
+  jq       https://jqlang.github.io/jq/download/
+  node     https://nodejs.org
+  python3  https://www.python.org/downloads/
+
+To accept the risk and work without this guard, set GROUNDPLAN_HOOK_STRICT=0."
+  fi
+
+  printf '%s\n' "WARNING: $1 is INACTIVE — no JSON engine, and GROUNDPLAN_HOOK_STRICT=0. $2 is unchecked." >&2
+  return 0
+}
+
+# gp_json_key <file> <key> — scalar, or array elements one per line
+gp_json_key() {
+  local file="$1" key="$2"
+  [ -f "$file" ] || return 1
+  # tr -d '\r': a config file saved with CRLF would otherwise poison every '$'-anchored pattern.
+  case "$GROUNDPLAN_JSON_ENGINE" in
+    jq) jq -r --arg k "$key" '.[$k] // empty | if type=="array" then .[] elif type=="object" then to_entries[] | "\(.key)\t\(.value)" else . end' "$file" 2>/dev/null | tr -d '\r' ;;
+    node) node "$GROUNDPLAN_LIB_DIR/json_get.mjs" key "$key" <"$file" 2>/dev/null | tr -d '\r' ;;
+    python3|python) "$GROUNDPLAN_JSON_ENGINE" "$GROUNDPLAN_LIB_DIR/json_get.py" key "$key" <"$file" 2>/dev/null | tr -d '\r' ;;
+    *) return 1 ;;
+  esac
+}
+
+# gp_json_field <mode> — reads a hook payload on stdin; mode is path|content
+gp_json_field() {
+  local mode="$1"
+  case "$GROUNDPLAN_JSON_ENGINE" in
+    jq)
+      if [ "$mode" = path ]; then
+        jq -r '.tool_input.file_path // .tool_input.path // .tool_input.notebook_path // empty' 2>/dev/null
+      else
+        jq -r '[.tool_input.content, .tool_input.new_string, (.tool_input.edits[]?.new_string)] | map(select(.!=null)) | join("\n")' 2>/dev/null
+      fi ;;
+    node) node "$GROUNDPLAN_LIB_DIR/json_get.mjs" "$mode" 2>/dev/null ;;
+    python3|python) "$GROUNDPLAN_JSON_ENGINE" "$GROUNDPLAN_LIB_DIR/json_get.py" "$mode" 2>/dev/null ;;
+    *) return 1 ;;
+  esac | tr -d '\r'
+}
+
+gp_env_name() {
+  printf 'GROUNDPLAN_HOOK_%s' "$(printf '%s' "$1" | sed -E 's/([a-z0-9])([A-Z])/\1_\2/g' | tr '[:lower:]' '[:upper:]')"
+}
+
+gp_env_value() {
+  eval "printf '%s' \"\${$(gp_env_name "$1"):-}\""
+}
+
+gp_config_path() {
+  local override; override="$(gp_env_value configPath)"
+  if [ -n "$override" ]; then printf '%s' "$override"; return; fi
+  gp_json_key "$GROUNDPLAN_DEFAULTS_FILE" configPath
+}
+
+# gp_config <key> — one value per line, so arrays iterate naturally
+gp_config() {
+  local key="$1" value repo_file
+  value="$(gp_env_value "$key")"
+  if [ -n "$value" ]; then
+    printf '%s' "$value" | tr ',' '\n' | sed -E 's/^[[:space:]]+|[[:space:]]+$//g' | grep -v '^$'
+    return
+  fi
+
+  repo_file="$(gp_config_path)"
+  if [ -f "$repo_file" ]; then
+    value="$(gp_json_key "$repo_file" "$key")"
+    if [ -n "$value" ]; then printf '%s\n' "$value"; return; fi
+  fi
+
+  gp_json_key "$GROUNDPLAN_DEFAULTS_FILE" "$key"
+}
+
+# Strip the repo root so absolute tool paths match repo-relative rules.
+gp_slash_path() {
+  local norm root
+  norm="$(printf '%s' "$1" | tr '\\' '/')"
+  root="$(git rev-parse --show-toplevel 2>/dev/null | tr '\\' '/')"
+  [ -n "$root" ] && norm="${norm#"$root"/}"
+  printf '%s' "$norm"
+}
+
+# grep -P handles the (?i) and \d in defaults.json; -E silently mismatches them.
+# Probe with a pattern that must match — an empty pattern exits 1 (no match) even where -P works.
+if printf 'a' | grep -qP 'a' >/dev/null 2>&1; then GROUNDPLAN_GREP_OPT=-P; else GROUNDPLAN_GREP_OPT=-E; fi
+
+gp_grep() { grep -q "$GROUNDPLAN_GREP_OPT" "$1"; }
+
+gp_match_any() {
+  local value="$1" pattern
+  [ -n "$value" ] || return 1
+  while IFS= read -r pattern; do
+    [ -n "$pattern" ] || continue
+    printf '%s' "$value" | gp_grep "$pattern" && return 0
+  done
+  return 1
+}
+
+# Exit 2 is the block signal; stderr is what the model reads back.
+gp_deny() {
+  printf '%s\n' "$1" >&2
+  exit 2
+}

package/registry/hooks/_lib/defaults.json

@@ -0,0 +1,76 @@
+{
+  "$comment": "The ONE default table for every registry hook. Override per-repo via configPath, or per-key via GROUNDPLAN_HOOK_<UPPER_SNAKE> env vars. Nothing below may be duplicated into hook logic.",
+
+  "configPath": ".agent/hooks.config.json",
+
+  "protectedPaths": [
+    "(^|/)\\.env[^/]*$",
+    "(^|/)secrets?[^/]*$",
+    "(^|/)[^/]*\\.pem$",
+    "(^|/)[^/]*\\.key$",
+    "(^|/)\\.git/",
+    "(^|/)package-lock\\.json$",
+    "(^|/)yarn\\.lock$",
+    "(^|/)pnpm-lock\\.yaml$",
+    "(^|/)poetry\\.lock$",
+    "(^|/)Cargo\\.lock$",
+    "(^|/)go\\.sum$"
+  ],
+
+  "readOnlyPaths": [],
+
+  "protectedAllowlist": [
+    "(^|/)\\.env\\.example$",
+    "(^|/)\\.env\\.sample$",
+    "(^|/)\\.env\\.template$"
+  ],
+
+  "commitTypes": [
+    "feat", "fix", "docs", "style", "refactor", "perf",
+    "test", "build", "ci", "chore", "revert"
+  ],
+  "commitSubjectMaxLength": 72,
+  "commitRequireScope": false,
+
+  "secretPatterns": [
+    "AKIA[0-9A-Z]{16}",
+    "ASIA[0-9A-Z]{16}",
+    "gh[pousr]_[A-Za-z0-9]{36,}",
+    "github_pat_[A-Za-z0-9_]{60,}",
+    "sk-ant-[A-Za-z0-9_-]{20,}",
+    "sk-[A-Za-z0-9]{32,}",
+    "xox[abprs]-[A-Za-z0-9-]{10,}",
+    "AIza[0-9A-Za-z_-]{35}",
+    "-----BEGIN [A-Z ]*PRIVATE KEY-----",
+    "eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}",
+    "(?i)(api[_-]?key|secret|passwd|password|token)\\s*[:=]\\s*[\"'][^\"'\\s]{12,}[\"']",
+    "postgres(ql)?://[^\\s:]+:[^\\s@]+@",
+    "mongodb(\\+srv)?://[^\\s:]+:[^\\s@]+@"
+  ],
+
+  "secretAllowlist": [
+    "(^|/)\\.env\\.example$",
+    "(^|/)\\.env\\.sample$",
+    "(^|/)[^/]*\\.lock$",
+    "(^|/)(test|tests|spec|__tests__|fixtures|testdata)/",
+    "(^|/)registry/hooks/_lib/defaults\\.json$"
+  ],
+  "secretPlaceholderPattern": "(?i)(\\b(example|sample|placeholder|dummy|changeme|redacted|your|fake|test)\\b|your[_-]|\\bx{4,}\\b|<[^>]+>|\\$\\{[^}]+\\})",
+
+  "formatters": {
+    ".ts": "npx --no-install prettier --write",
+    ".tsx": "npx --no-install prettier --write",
+    ".js": "npx --no-install prettier --write",
+    ".jsx": "npx --no-install prettier --write",
+    ".json": "npx --no-install prettier --write",
+    ".css": "npx --no-install prettier --write",
+    ".md": "npx --no-install prettier --write",
+    ".py": "ruff format",
+    ".go": "gofmt -w",
+    ".rs": "rustfmt --edition 2021",
+    ".cs": "dotnet format --include"
+  },
+  "formatTimeoutMs": 15000,
+
+  "boundaries": []
+}

package/registry/hooks/_lib/json_get.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// jq fallback for the bash hooks. Zero dependencies — reads JSON on stdin, prints lines.
+// Mirrors json_get.py exactly; hook-shape.test.ts asserts the two agree.
+
+// Write and Edit carry the new text under different keys.
+const CONTENT_FIELDS = ['content', 'new_string', 'new_source'];
+const PATH_FIELDS = ['file_path', 'path', 'notebook_path'];
+
+function emit(value) {
+  if (value === null || value === undefined) return;
+  if (Array.isArray(value)) {
+    for (const item of value) process.stdout.write(`${item}\n`);
+  } else if (typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) process.stdout.write(`${k}\t${v}\n`);
+  } else {
+    process.stdout.write(`${value}\n`);
+  }
+}
+
+async function read() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+const mode = process.argv[2] ?? 'key';
+
+let data;
+try {
+  data = JSON.parse(await read());
+} catch {
+  process.exit(1);
+}
+
+if (mode === 'key') {
+  emit(data?.[process.argv[3]]);
+  process.exit(0);
+}
+
+const toolInput = data?.tool_input ?? {};
+
+if (mode === 'path') {
+  for (const field of PATH_FIELDS) {
+    if (toolInput[field]) {
+      process.stdout.write(`${toolInput[field]}\n`);
+      break;
+    }
+  }
+  process.exit(0);
+}
+
+if (mode === 'content') {
+  const parts = CONTENT_FIELDS.filter((f) => toolInput[f]).map((f) => toolInput[f]);
+  for (const edit of toolInput.edits ?? []) parts.push(edit?.new_string ?? '');
+  process.stdout.write(`${parts.filter(Boolean).join('\n')}\n`);
+  process.exit(0);
+}
+
+process.exit(1);

package/registry/hooks/_lib/json_get.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""jq fallback for the bash hooks. Stdlib only — reads JSON on stdin, prints lines."""
+
+import json
+import sys
+
+# Windows text mode would emit \r\n, and a trailing \r breaks every '$'-anchored config pattern.
+sys.stdout.reconfigure(newline="\n")
+
+# Write and Edit carry the new text under different keys.
+CONTENT_FIELDS = ("content", "new_string", "new_source")
+PATH_FIELDS = ("file_path", "path", "notebook_path")
+
+
+def emit(value):
+    if value is None:
+        return
+    if isinstance(value, list):
+        for item in value:
+            print(item)
+    elif isinstance(value, dict):
+        for k, v in value.items():
+            print(f"{k}\t{v}")
+    elif isinstance(value, bool):
+        print("true" if value else "false")
+    else:
+        print(value)
+
+
+def main():
+    mode = sys.argv[1] if len(sys.argv) > 1 else "key"
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 1
+
+    if mode == "key":
+        emit(data.get(sys.argv[2]))
+        return 0
+
+    tool_input = data.get("tool_input") or {}
+
+    if mode == "path":
+        for field in PATH_FIELDS:
+            if tool_input.get(field):
+                print(tool_input[field])
+                break
+        return 0
+
+    if mode == "content":
+        parts = [tool_input[f] for f in CONTENT_FIELDS if tool_input.get(f)]
+        parts += [e.get("new_string", "") for e in tool_input.get("edits") or []]
+        print("\n".join(p for p in parts if p))
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/registry/hooks/architecture-boundary-check/hook.ps1

@@ -0,0 +1,46 @@
+# PreToolUse (Edit|Write): block a write that introduces an import across a declared boundary.
+# Rule syntax: "<pathRegex> !> <denyImportRegex> :: <why>". No boundaries declared = hook is inert.
+. (Join-Path $PSScriptRoot '..\_lib\config.ps1')
+
+$rules = @(Get-GroundplanConfig 'boundaries')
+if ($rules.Count -eq 0) { exit 0 }
+
+$payload = Read-GroundplanPayload
+$path = Get-GroundplanPayloadPath $payload
+$content = Get-GroundplanPayloadContent $payload
+if (-not $path -or -not $content) { exit 0 }
+
+$norm = ConvertTo-GroundplanSlashPath $path
+
+foreach ($rule in $rules) {
+    $parts = $rule -split '\s+!>\s+', 2
+    if ($parts.Count -ne 2) { continue }
+    $pathPattern = $parts[0].Trim()
+    $rest = $parts[1] -split '\s+::\s+', 2
+    $denyPattern = $rest[0].Trim()
+    $why = if ($rest.Count -eq 2) { $rest[1].Trim() } else { 'declared architecture boundary' }
+
+    if ($norm -notmatch $pathPattern) { continue }
+
+    $lineNumber = 0
+    foreach ($line in ($content -split "`r?`n")) {
+        $lineNumber++
+        # Only import/using/require lines carry dependency direction; a string mention does not.
+        if ($line -notmatch '^\s*(import|from|using|require|#include|use\s)') { continue }
+        if ($line -notmatch $denyPattern) { continue }
+
+        Deny-GroundplanTool @"
+BLOCKED: '$norm' crosses a declared architecture boundary.
+
+  line $lineNumber : $($line.Trim())
+  rule           : $pathPattern !> $denyPattern
+  why            : $why
+
+Depend on an abstraction owned by this side of the boundary, or move the code to the layer that
+may legally hold the dependency. If the boundary itself is wrong, change it in AGENTS.md and
+record an ADR — do not route around it here.
+"@
+    }
+}
+
+exit 0

package/registry/hooks/architecture-boundary-check/hook.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# PreToolUse (Edit|Write): block a write that introduces an import across a declared boundary.
+# Rule syntax: "<pathRegex> !> <denyImportRegex> :: <why>". No boundaries declared = hook is inert.
+set -uo pipefail
+# shellcheck source=../_lib/config.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)/config.sh"
+
+gp_json_unavailable && exit 0
+
+rules="$(gp_config boundaries)"
+[ -n "$rules" ] || exit 0
+
+payload="$(cat)"
+path="$(printf '%s' "$payload" | gp_json_field path)"
+content="$(printf '%s' "$payload" | gp_json_field content)"
+[ -n "$path" ] && [ -n "$content" ] || exit 0
+
+norm="$(gp_slash_path "$path")"
+
+while IFS= read -r rule; do
+  [ -n "$rule" ] || continue
+  path_pattern="$(printf '%s' "$rule" | sed -E 's/[[:space:]]+!>[[:space:]]+.*//')"
+  remainder="$(printf '%s' "$rule" | sed -E 's/.*[[:space:]]+!>[[:space:]]+//')"
+  deny_pattern="$(printf '%s' "$remainder" | sed -E 's/[[:space:]]+::[[:space:]]+.*//')"
+  why="$(printf '%s' "$remainder" | sed -nE 's/.*[[:space:]]+::[[:space:]]+(.*)/\1/p')"
+  [ -n "$why" ] || why="declared architecture boundary"
+  [ "$path_pattern" = "$remainder" ] && continue
+
+  printf '%s' "$norm" | gp_grep "$path_pattern" || continue
+
+  # Only import/using/require lines carry dependency direction; a string mention does not.
+  hit="$(printf '%s' "$content" | grep -nE '^[[:space:]]*(import|from|using|require|#include|use )' \
+        | grep -P "$deny_pattern" 2>/dev/null | head -n1 || true)"
+  [ -n "$hit" ] || continue
+
+  gp_deny "BLOCKED: '$norm' crosses a declared architecture boundary.
+
+  line ${hit%%:*} : $(printf '%s' "${hit#*:}" | sed -E 's/^[[:space:]]+//')
+  rule           : $path_pattern !> $deny_pattern
+  why            : $why
+
+Depend on an abstraction owned by this side of the boundary, or move the code to the layer that
+may legally hold the dependency. If the boundary itself is wrong, change it in AGENTS.md and
+record an ADR — do not route around it here."
+done <<EOF
+$rules
+EOF
+
+exit 0

package/registry/hooks/architecture-boundary-check/hook.yaml

@@ -0,0 +1,18 @@
+id: architecture-boundary-check
+kind: hook
+name: Architecture Boundary Check
+description: Blocks an Edit/Write that introduces an import crossing a declared architecture boundary. Inert until the repo declares boundaries.
+tags: [architecture, boundaries, pretooluse]
+targets: [claude-code]
+requiresCapability: [hooks]
+# Nothing to enforce until the repo declares its boundaries, so the adapter can skip emitting it.
+when: boundaries.length > 0
+
+event: PreToolUse
+matcher: Edit|Write
+entrypoints:
+  powershell: hook.ps1
+  bash: hook.sh
+config: [boundaries]
+# Rule syntax: "<pathRegex> !> <denyImportRegex> :: <why>"
+# Example:     "^src/domain/ !> src/(infrastructure|api|ui)/ :: domain must not depend on outer layers"