guardian-framework 0.1.0

package/templates/pi/scripts/validate-ubiquitous-language.sh

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-ubiquitous-language.sh — Detect Code Drift from Ubiquitous Language
+#
+# Parses .pi/domain/ubiquitous-language.md for the canonical term list,
+# then greps src/ for class/function/variable/type names, flagging any
+# that use an alias/synonym instead of the canonical term.
+#
+# Canonical Reference: .pi/architecture/modules/core-libraries.md
+# Implements: Ubiquitous Language drift detection
+# Issue: (add issue number here)
+# Last Architecture Sync: 2026-05-31
+#
+# Usage:
+#   bash .pi/scripts/validate-ubiquitous-language.sh [src_dir]
+#
+# Exit codes:
+#   0 = No drift detected (all code uses canonical terms)
+#   1 = Drift detected (one or more aliases found)
+# ============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+GLOSSARY_FILE="${PROJECT_ROOT}/.pi/domain/ubiquitous-language.md"
+SRC_DIR="${1:-${PROJECT_ROOT}/src}"
+
+PASS_COUNT=0; ERROR_COUNT=0; WARN_COUNT=0; DRIFT_FOUND=0
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
+pass()  { echo -e "${GREEN}✅ PASS${NC}  $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail()  { echo -e "${RED}❌ FAIL${NC}  $1"; ERROR_COUNT=$((ERROR_COUNT + 1)); DRIFT_FOUND=1; }
+warn()  { echo -e "${YELLOW}⚠️  WARN${NC}  $1"; WARN_COUNT=$((WARN_COUNT + 1)); }
+info()  { echo -e "${BLUE}ℹ️  INFO${NC}  $1"; }
+
+echo "============================================"
+echo "  Ubiquitous Language Validation"
+echo "============================================"
+echo ""
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Check: Glossary file exists
+# ─────────────────────────────────────────────────────────────────────────────
+echo "--- Preflight ---"
+if [ ! -f "$GLOSSARY_FILE" ]; then
+    fail "Glossary not found at: $GLOSSARY_FILE"
+    info "Run the validator from the project root."
+    echo ""
+    echo "============================================"
+    echo "  Summary"
+    echo "============================================"
+    echo -e "  Passed:   ${GREEN}0${NC}"
+    echo -e "  Failed:   ${RED}1${NC}"
+    exit 1
+fi
+pass "Glossary found: $GLOSSARY_FILE"
+
+if [ ! -d "$SRC_DIR" ]; then
+    fail "Source directory not found: $SRC_DIR"
+    echo ""
+    echo "============================================"
+    echo "  Summary"
+    echo "============================================"
+    echo -e "  Passed:   ${GREEN}0${NC}"
+    echo -e "  Failed:   ${RED}1${NC}"
+    exit 1
+fi
+pass "Source directory found: $SRC_DIR"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Parse Glossary — extract canonical terms and aliases
+# ─────────────────────────────────────────────────────────────────────────────
+echo ""
+echo "--- Parsing Glossary ---"
+
+# Parse the markdown table:
+# Format: | Term | Definition | Bounded Context | Aliases/Synonyms | Examples |
+# We need columns 1 (Term) and 4 (Aliases/Synonyms)
+#
+# Strategy: extract lines starting with "|", skip header/separator, parse columns
+
+declare -a CANONICAL_TERMS=()
+declare -a ALIAS_LISTS=()      # Same index as CANONICAL_TERMS, pipe-separated aliases
+GLOSSARY_ENTRIES=0
+
+while IFS='|' read -r _ term _ _ aliases _; do
+    # Trim whitespace
+    term=$(echo "$term" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    aliases=$(echo "$aliases" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+    # Skip header row, separator row, and empty rows
+    [ -z "$term" ] && continue
+    [ "$term" = "Term" ] && continue
+    [ "$(echo "$term" | tr -d ' -')" = "" ] && continue
+
+    # Skip if term contains only dashes (separator row like |------|)
+    [[ "$term" =~ ^-+$ ]] && continue
+
+    CANONICAL_TERMS+=("$term")
+    ALIAS_LISTS+=("$aliases")
+    GLOSSARY_ENTRIES=$((GLOSSARY_ENTRIES + 1))
+done < <(grep '^|' "$GLOSSARY_FILE")
+
+if [ "$GLOSSARY_ENTRIES" -eq 0 ]; then
+    fail "No glossary entries found in $GLOSSARY_FILE"
+    echo ""
+    echo "============================================"
+    echo "  Summary"
+    echo "============================================"
+    echo -e "  Passed:   ${GREEN}0${NC}"
+    echo -e "  Failed:   ${RED}1${NC}"
+    exit 1
+fi
+pass "Parsed $GLOSSARY_ENTRIES glossary entries"
+
+# Debug: show parsed terms and aliases
+for i in "${!CANONICAL_TERMS[@]}"; do
+    term="${CANONICAL_TERMS[$i]}"
+    aliases="${ALIAS_LISTS[$i]}"
+    if [ -n "$aliases" ]; then
+        info "  • \"$term\" → aliases: $aliases"
+    fi
+done
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Find TypeScript identifiers in src/
+# ─────────────────────────────────────────────────────────────────────────────
+echo ""
+echo "--- Scanning Source Code ---"
+
+TS_FILES=$(find "$SRC_DIR" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null | sort)
+TS_FILE_COUNT=$(echo "$TS_FILES" | grep -c . 2>/dev/null || echo "0")
+
+if [ "$TS_FILE_COUNT" -eq 0 ]; then
+    warn "No TypeScript files found in $SRC_DIR"
+    echo ""
+    echo "============================================"
+    echo "  Summary"
+    echo "============================================"
+    echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+    echo -e "  Warnings: ${YELLOW}${WARN_COUNT}${NC}"
+    exit 0
+fi
+pass "Found $TS_FILE_COUNT TypeScript files to scan"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Extract identifiers from TypeScript files
+# ─────────────────────────────────────────────────────────────────────────────
+# We extract:
+#   - Class/interface/type/enum names (after keyword)
+#   - Function names (after "function" or in arrow-function const assignments)
+#   - Exported const/variable names
+#   - Import aliases (e.g., "import { X as Y }")
+#   - Named exports (export function/class/interface/type)
+
+# Build a temporary file of all identifiers with their file:line locations
+IDENTIFIER_FILE=$(mktemp)
+trap 'rm -f "$IDENTIFIER_FILE"' EXIT
+
+# Use perl for portable regex extraction with capturing groups
+perl -nle '
+    # Skip non-source files
+    next unless -f $ARGV;
+    
+    my $file = $ARGV;
+    my $line_no = $.;
+    chomp;
+    
+    # Match: export (class|interface|type|enum|function) Name
+    if (/\bexport\s+(class|interface|type|enum|function)\s+([A-Za-z_][A-Za-z0-9_]*)/) {
+        print "$file:$line_no:$2";
+    }
+    
+    # Match: (class|interface|type|enum|function) Name (without export)
+    if (/\b(class|interface|type|enum|function)\s+([A-Za-z_][A-Za-z0-9_]*)/) {
+        print "$file:$line_no:$2";
+    }
+    
+    # Match: (const|let|var) Name
+    if (/\b(const|let|var)\s+([A-Za-z_][A-Za-z0-9_]*)\s*[=:]/) {
+        print "$file:$line_no:$2";
+    }
+    
+    # Match: export default (class|function) Name
+    if (/\bexport\s+default\s+(class|function)\s+([A-Za-z_][A-Za-z0-9_]*)/) {
+        print "$file:$line_no:$2";
+    }
+    
+    # Match: import { ... as Alias }
+    if (/\bimport\s*\{[^}]*\}\s*from/) {
+        # Find all "as X" patterns
+        my $rest = $_;
+        while ($rest =~ /\bas\s+([A-Za-z_][A-Za-z0-9_]*)/g) {
+            print "$file:$line_no:$1";
+        }
+    }
+    
+    # Match: function Name(...)
+    if (/\bfunction\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/) {
+        print "$file:$line_no:$1";
+    }
+' $TS_FILES 2>/dev/null >> "$IDENTIFIER_FILE" || true
+
+IDENTIFIER_COUNT=$(wc -l < "$IDENTIFIER_FILE" | tr -d ' ')
+if [ "$IDENTIFIER_COUNT" -eq 0 ]; then
+    warn "No identifiers extracted from TypeScript files"
+else
+    info "Extracted $IDENTIFIER_COUNT identifiers"
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Check each identifier against canonical terms and aliases
+# ─────────────────────────────────────────────────────────────────────────────
+echo ""
+echo "--- Drift Detection ---"
+
+DRIFT_COUNT=0
+
+for i in "${!CANONICAL_TERMS[@]}"; do
+    canonical="${CANONICAL_TERMS[$i]}"
+    aliases="${ALIAS_LISTS[$i]}"
+
+    # Skip if no aliases defined for this term
+    [ -z "$aliases" ] && continue
+
+    # Split aliases by comma and check each one
+    IFS=',' read -ra ALIAS_ARRAY <<< "$aliases"
+    for alias in "${ALIAS_ARRAY[@]}"; do
+        # Trim whitespace
+        alias=$(echo "$alias" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        [ -z "$alias" ] && continue
+
+        # Check if this alias is the same as the canonical term (skip)
+        if [ "$alias" = "$canonical" ]; then
+            continue
+        fi
+
+        # Search identifiers for this alias
+        # Use grep -F for exact string matching, -w for whole word
+        MATCHES=$(grep -F ":$alias" "$IDENTIFIER_FILE" 2>/dev/null || true)
+
+        if [ -n "$MATCHES" ]; then
+            # Found drift — this alias is used in code
+            while IFS= read -r match; do
+                # Parse file:line:identifier
+                match_file=$(echo "$match" | cut -d: -f1)
+                match_line=$(echo "$match" | cut -d: -f2)
+                match_id=$(echo "$match" | cut -d: -f3-)
+
+                # Convert to relative path
+                rel_file="${match_file#$PROJECT_ROOT/}"
+
+                fail "Alias \"$alias\" used instead of canonical \"$canonical\" → ${rel_file}:${match_line} (identifier: $match_id)"
+                DRIFT_COUNT=$((DRIFT_COUNT + 1))
+            done <<< "$MATCHES"
+        fi
+    done
+done
+
+if [ "$DRIFT_COUNT" -eq 0 ]; then
+    pass "No drift detected — all code uses canonical terms"
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Also check for case variations of canonical terms
+# Note: Canonical term case variation checks are intentionally omitted.
+# TypeScript convention uses PascalCase for types (e.g., Result, Manifest)
+# and camelCase for variable instances (e.g., result, manifest).
+# Both are correct in context and not drift.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Summary
+# ─────────────────────────────────────────────────────────────────────────────
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Warnings: ${YELLOW}${WARN_COUNT}${NC}"
+echo -e "  Drift:    ${RED}${DRIFT_COUNT}${NC}"
+
+if [ "$DRIFT_FOUND" -eq 1 ]; then
+    echo ""
+    echo -e "${RED}❌ Ubiquitous language drift detected.${NC}"
+    echo "  Fix: Replace aliases with canonical terms in the listed files."
+    echo "  Then re-run this validator."
+    exit 1
+fi
+
+echo ""
+echo -e "${GREEN}✅ Ubiquitous language validation passed.${NC}"
+exit 0

package/templates/pi/scripts/validation-cache.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validation-cache.sh — Validation Result Caching System
+#
+# Caches passed validation checks so retries only re-check failed items.
+#
+# Usage:
+#   bash .pi/scripts/validation-cache.sh init [task-id]
+#   bash .pi/scripts/validation-cache.sh record [task-id] [validator] [check] [pass|fail]
+#   bash .pi/scripts/validation-cache.sh get-failed [task-id] [validator]
+#   bash .pi/scripts/validation-cache.sh summary [task-id]
+#   bash .pi/scripts/validation-cache.sh clear [task-id]
+#
+# Exit codes: 0 = success, 1 = error
+# ============================================================================
+set -euo pipefail
+
+CACHE_DIR=".claude/validation-cache"
+mkdir -p "$CACHE_DIR"
+
+ACTION="${1:-help}"
+TASK_ID="${2:-}"
+VALIDATOR="${3:-}"
+CHECK="${4:-}"
+STATUS="${5:-}"
+
+CACHE_FILE() { echo "${CACHE_DIR}/${TASK_ID}.cache"; }
+
+# ---------------------------------------------------------------------------
+# Init — create empty cache for a task
+# ---------------------------------------------------------------------------
+init_cache() {
+    if [ -z "$TASK_ID" ]; then
+        echo "Usage: $0 init <task-id>"
+        exit 1
+    fi
+    echo "# Validation Cache: $TASK_ID" > "$(CACHE_FILE)"
+    echo "# Format: validator|check|status|timestamp" >> "$(CACHE_FILE)"
+    echo "Initialized cache for task: $TASK_ID"
+}
+
+# ---------------------------------------------------------------------------
+# Record — log a validation result
+# ---------------------------------------------------------------------------
+record_result() {
+    if [ -z "$TASK_ID" ] || [ -z "$VALIDATOR" ] || [ -z "$CHECK" ] || [ -z "$STATUS" ]; then
+        echo "Usage: $0 record <task-id> <validator> <check> <pass|fail>"
+        exit 1
+    fi
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "${VALIDATOR}|${CHECK}|${STATUS}|${TIMESTAMP}" >> "$(CACHE_FILE)"
+}
+
+# ---------------------------------------------------------------------------
+# Get Failed — list only failed checks for a validator (for retry)
+# ---------------------------------------------------------------------------
+get_failed() {
+    if [ -z "$TASK_ID" ] || [ -z "$VALIDATOR" ]; then
+        echo "Usage: $0 get-failed <task-id> <validator>"
+        exit 1
+    fi
+    if [ ! -f "$(CACHE_FILE)" ]; then
+        echo "No cache found for task: $TASK_ID"
+        exit 1
+    fi
+    FAILED=$(grep "^${VALIDATOR}|" "$(CACHE_FILE)" | grep "|fail|" | cut -d'|' -f2 || true)
+    if [ -z "$FAILED" ]; then
+        echo "ALL_PASSED"
+    else
+        echo "$FAILED"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Summary — show full validation status for a task
+# ---------------------------------------------------------------------------
+show_summary() {
+    if [ -z "$TASK_ID" ]; then
+        echo "Usage: $0 summary <task-id>"
+        exit 1
+    fi
+    if [ ! -f "$(CACHE_FILE)" ]; then
+        echo "No cache found for task: $TASK_ID"
+        exit 1
+    fi
+
+    TOTAL=$(grep -v "^#" "$(CACHE_FILE)" | wc -l | tr -d ' ')
+    PASSED=$(grep -v "^#" "$(CACHE_FILE)" | grep "|pass|" | wc -l | tr -d ' ')
+    FAILED=$(grep -v "^#" "$(CACHE_FILE)" | grep "|fail|" | wc -l | tr -d ' ')
+
+    echo "============================================"
+    echo "  Validation Summary: $TASK_ID"
+    echo "============================================"
+    echo "  Total:  $TOTAL"
+    echo "  Passed: $PASSED"
+    echo "  Failed: $FAILED"
+    echo ""
+
+    if [ "$FAILED" -gt 0 ]; then
+        echo "Failed checks:"
+        grep -v "^#" "$(CACHE_FILE)" | grep "|fail|" | while IFS='|' read -r val chk sts ts; do
+            echo "  [$val] $chk"
+        done
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Clear — remove cache for a task
+# ---------------------------------------------------------------------------
+clear_cache() {
+    if [ -z "$TASK_ID" ]; then
+        echo "Usage: $0 clear <task-id>"
+        exit 1
+    fi
+    rm -f "$(CACHE_FILE)"
+    echo "Cleared cache for task: $TASK_ID"
+}
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+case "$ACTION" in
+    init)        init_cache ;;
+    record)      record_result ;;
+    get-failed)  get_failed ;;
+    summary)     show_summary ;;
+    clear)       clear_cache ;;
+    *)
+        echo "Usage: $0 {init|record|get-failed|summary|clear} [args...]"
+        echo ""
+        echo "Commands:"
+        echo "  init <task-id>                              Create empty cache"
+        echo "  record <task-id> <validator> <check> <status>  Record result"
+        echo "  get-failed <task-id> <validator>            List failed checks"
+        echo "  summary <task-id>                           Show full status"
+        echo "  clear <task-id>                             Remove cache"
+        exit 1
+        ;;
+esac

package/templates/pi/skills/agents/architecture-coordinator.md

@@ -0,0 +1,178 @@
+---
+name: architecture-coordinator
+description: Master orchestrator. Classifies scope, reviews ADRs, challenges architecture, spawns validators, makes final decisions. Use for multi-component features or complex changes.
+model: inherit
+tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# Architecture Coordinator
+
+You are the master orchestrator. You classify tasks, spawn validators, and make final decisions.
+
+## Understand Before You Build
+
+**THE MOST IMPORTANT RULE: YOU DON'T ASSUME, YOU VERIFY.** Ground all communication in evidence-based facts. Follow your knowledge but always check your work and back it up with hard, up-to-date data that you looked up yourself.
+
+Never start implementing until you are **100% certain** of what needs to be done. If you catch yourself thinking "I think this is how it works" — STOP. That's a signal to ask or scout, not to start coding.
+
+**Fill knowledge gaps with:**
+- **`ask_user_question`** — ambiguous requirements, preference between approaches, any detail that would materially change the implementation. One question per call. Never guess what the user wants.
+- **Automated validation scripts** — how the codebase works, which files are involved, what patterns exist. Run `grep`, `find`, `ls`, targeted `read`.
+- **Subagent validators** — architecture, security, operations compliance.
+
+**Before any non-trivial implementation, you must know:**
+- Exactly what the change does (confirmed with user)
+- Exactly which files are involved (verified with grep/find/read)
+- Exactly which patterns to follow (verified in existing code)
+
+If any of those are fuzzy, you're not ready to implement.
+
+## Context (Load ONCE)
+- `.pi/architecture/modules/` — module architecture docs (read relevant modules only)
+- `.pi/architecture/decisions/` — ADRs (review all accepted/proposed ADRs relevant to scope)
+- `.pi/architecture/CHANGELOG.md` — recent architecture changes
+- `.pi/context/project.md` — project knowledge
+- `.pi/context/checklists.md` — validation checklists
+- `.pi/context/output-formats.md` — report templates
+
+## Protocol
+
+### Phase 1: Discovery
+1. **Classify scope** using scope table (files changed, lines affected, module touched)
+2. **Load relevant ADRs** — find all accepted/proposed ADRs that affect the modules in scope
+3. **Review module docs** — read `.pi/architecture/modules/[affected-module].md` for affected modules only
+
+### Phase 2: Architecture Challenge
+4. **Challenge the current design** — before accepting the approach, ask:
+   - Does this align with existing ADRs? If not, should we update them or propose a new ADR?
+   - Are there better patterns already established in the codebase? (grep for similar implementations)
+   - Does this create tight coupling between modules? Check module dependency graph.
+   - Is there a simpler approach that achieves the same outcome?
+   - What are the long-term maintenance implications?
+5. **If architecture gaps found:** propose ADR updates or new ADRs *before* proceeding. Get user alignment.
+
+### Phase 3: Validation
+6. **Determine validators** per scope classification
+7. **Spawn validators in parallel** for plan review (NOT code review yet)
+8. **Synthesize results** → Design Proposal (use `.pi/context/output-formats.md`)
+
+### Phase 4: Approval & Implementation
+9. **Get user approval** for Complex/Critical scope
+10. **Spawn code-developer** with implementation plan + validation contract
+
+### Phase 5: Post-Code
+11. **Run automated validators** (scripts)
+12. **Run LLM validators** only for wiring checks
+13. **Final decision** → approve, condition, or reject
+
+### Phase 6: Architecture Sync
+14. **Update ADRs** if the implementation diverged from the original decision
+15. **Add CHANGELOG entry** for any architecture-level changes
+
+## Context Hygiene
+
+Your context window is a finite, non-renewable resource. Every file you read directly stays in your context forever.
+
+**Default to targeted reads for exploration.** If the task involves understanding how something works across multiple files, use `grep` and `find` to locate relevant code, then read only the specific files you need. Get a concise understanding back. Your context stays clean.
+
+**Use direct reads/greps ONLY when:**
+- You need to verify 1-2 lines right before making an edit
+- You already know exactly what file and what you're looking for
+- The answer is a single grep hit
+
+**Never explore a codebase by reading entire files.** Use targeted greps and targeted reads.
+
+## Architecture Challenge Framework
+
+When reviewing any change, apply these lenses:
+
+| Lens | Question | Check |
+|------|----------|-------|
+| **ADR Compliance** | Does this respect existing architecture decisions? | Read relevant ADRs in `.pi/architecture/decisions/` |
+| **Pattern Consistency** | Does this follow established codebase patterns? | Grep for similar implementations in affected modules |
+| **Coupling** | Does this increase inter-module dependencies? | Check `## Dependencies` sections in module docs |
+| **Simplicity** | Is this the simplest approach that works? | Challenge abstractions, prefer 3 similar lines over new interface |
+| **Maintainability** | Will this be easy to change in 6 months? | Consider test coverage, documentation, naming |
+| **Security** | Does this introduce new attack surfaces? | Check input validation, auth boundaries, data flow |
+
+**When to challenge:**
+- **Always** for Complex and Critical scope changes
+- **Always** when touching core modules (check `## Components` in module docs)
+- **Always** when the proposed approach differs from existing patterns
+- **Optionally** for Simple/Moderate scope if you spot a red flag
+
+**How to challenge:**
+1. State the specific concern clearly
+2. Reference the relevant ADR, module doc, or existing code pattern
+3. Propose an alternative (don't just criticize — offer a path forward)
+4. Ask the user to decide: accept the challenge, or proceed with original approach
+
+## ADR Lifecycle Management
+
+### When to Create a New ADR
+- A new architectural decision affects multiple modules
+- An alternative approach was considered and rejected
+- A design pattern is being established that others should follow
+- A significant trade-off was made (performance vs. readability, etc.)
+
+### When to Update an Existing ADR
+- The implementation diverged from the original decision
+- New alternatives became viable (new library, new requirement)
+- The decision is being superseded by a newer approach
+
+### ADR Review Checklist
+Before accepting an ADR as valid:
+- [ ] Alternatives section has ≥ 2 options with honest pros/cons
+- [ ] Consequences section covers both positive and negative outcomes
+- [ ] Affected modules are listed and module docs would be updated
+- [ ] Required validators are identified
+- [ ] The decision is traceable to a specific problem/context
+
+## Scope → Validators Mapping
+
+| Scope | Validators | Notes |
+|-------|-----------|-------|
+| Simple | ci-mr (automated) | No LLM validators needed |
+| Moderate | architecture-validator | Plan review only; post-code = wiring check |
+| Complex | architecture + security | Plan review; post-code = wiring + security scan |
+| Critical | All validators + human | Plan review; post-code = wiring + manual checks |
+
+## Implementation Discipline
+
+### Keep It Simple
+
+Only make changes that are directly requested or clearly necessary. Don't add features, refactoring, or "improvements" beyond what was asked. Three similar lines of code is better than a premature abstraction. Prefer editing existing files over creating new ones.
+
+### Be Direct
+
+Prioritize technical accuracy over validation. No "Great question!" or "You're absolutely right!" — if the user's approach has issues, say so respectfully. Honest feedback over false agreement.
+
+### Investigate Before Fixing
+
+When something breaks, don't guess — investigate first. No fixes without understanding the root cause.
+
+1. **Observe** — read error messages, check full stack traces
+2. **Hypothesize** — form a theory based on evidence
+3. **Verify** — test the hypothesis before implementing a fix
+4. **Fix** — target the root cause, not the symptom
+
+If you're making random changes hoping something works, you don't understand the problem yet.
+
+### Verify Before Claiming Done
+
+Never claim success without proving it. Run the actual command, show the output.
+
+| Claim | Requires |
+|-------|----------|
+| "Tests pass" | Run tests, show output |
+| "Build succeeds" | Run build, show exit 0 |
+| "Bug fixed" | Reproduce original issue, show it's gone |
+| "Script works" | Run it, show expected output |
+
+## Rules
+- NEVER skip validation phases
+- NEVER override quality gates
+- NEVER allow duplicate types
+- Document all decisions
+- Verify wiring before merge (grep for callers, duplicates, imports)
+- Use automated scripts for ops/test/ci validation — do NOT spawn LLM agents for those

package/templates/pi/skills/agents/architecture-generator.md

@@ -0,0 +1,79 @@
+# Architecture Generator
+
+Generate canonical architecture modules from intent or existing documents.
+
+## Usage
+
+### From Intent
+
+```
+/architect-generate --intent "Build an auth system with JWT validation, OAuth2 SSO, Redis session management, and full observability"
+```
+
+### From Existing Documents
+
+```
+/architect-generate --from "docs/prd.md,docs/auth-design.md,docs/api-spec.md" --module "auth-system"
+```
+
+## Process
+
+1. **Analyze** the intent or existing documents
+2. **Identify** components, their responsibilities, and dependencies
+3. **Structure** the architecture module with proper status, dependencies, and descriptions
+4. **Validate** the module against Guardian's architecture conformance rules
+5. **Write** the canonical module to `.pi/architecture/modules/<name>.md`
+
+## Module Structure
+
+```markdown
+# Module Name
+
+## Component Name
+status: planned
+description: Clear, specific description of what this component does.
+depends: Other Component Name
+```
+
+## Rules
+
+- Each component must have a `status` (planned, in-progress, implemented, deprecated)
+- Each component must have a `description` that is specific and actionable
+- Dependencies must reference other component names in the same module or other modules
+- Components should be ordered by dependency (leaf dependencies first)
+- One module per bounded context or subsystem
+- Cross-module dependencies are documented in the `depends` field using `module:component` syntax
+
+## Architecture Conformance
+
+The generated module must satisfy these checks:
+
+1. **No orphaned components** — every component has at least one dependency or is a root
+2. **No circular dependencies** — components don't form dependency cycles
+3. **Clear separation of concerns** — components don't overlap in responsibility
+4. **Observable interfaces** — each component has clear inputs and outputs
+5. **DR-ready** — failure modes and recovery paths are considered
+
+## Examples
+
+### Intent-Based
+
+```
+You: /architect-generate --intent "Build a payment processing system with Stripe integration, webhook handling, idempotency, and reconciliation"
+
+Guardian generates: .pi/architecture/modules/payment-system.md
+  - Stripe API Integration (depends: none)
+  - Webhook Handler (depends: Stripe API Integration)
+  - Idempotency Layer (depends: Webhook Handler)
+  - Reconciliation Engine (depends: Idempotency Layer)
+  - Architecture Observability (depends: all above)
+```
+
+### Document-Based
+
+```
+You: /architect-generate --from "docs/prd-auth.md,docs/oauth2-spec.md" --module "auth-system"
+
+Guardian reads the documents, extracts components, and generates:
+  .pi/architecture/modules/auth-system.md
+```