guardian-framework 0.1.0

package/templates/pi/prompts/refactoring.md

@@ -0,0 +1,82 @@
+# Refactoring Workflow
+
+**Scope:** Moderate, Complex
+**Optimized for:** Safety — behavior must not change
+
+## Flow
+
+```
+Refactor Request
+    │
+    ▼
+┌─────────────────────────────────┐
+│ 1. COORDINATOR: Classify scope  │
+│    Determine affected modules   │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 2. CODE-DEVELOPER: Baseline     │
+│    Run all tests, record output │
+│    Run all validators, cache    │
+│    bash .pi/scripts/validation-cache.sh init <task-id>
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 3. ARCHITECTURE-VALIDATOR: Plan │
+│    Review refactor approach     │
+│    Ensure patterns preserved    │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 4. CODE-DEVELOPER: Refactor     │
+│    Small commits, one change at │
+│    a time                       │
+│    Run tests after each change  │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 5. AUTOMATED: Verify no regress │
+│    • validate-ci.sh             │
+│    • validate-tests.sh          │
+│    • validate-operations.sh     │
+│    Compare with baseline        │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 6. ARCHITECTURE-VALIDATOR: Wire │
+│    Verify wiring still correct  │
+│    • Callers exist              │
+│    • No duplicates              │
+│    • Modules used               │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 7. CI-MR: Create PR + merge     │
+└─────────────────────────────────┘
+```
+
+## Rules
+
+- **Behavior must not change** — all tests must pass with identical output
+- **Small commits** — one logical change per commit for easy revert
+- **Baseline first** — record test output before refactoring
+- **Wiring verification** — ensure all callers still work after refactor
+
+## Commands
+
+```bash
+# Baseline
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-tests.sh
+bash .pi/scripts/validate-operations.sh [src_dir]
+
+# Validation cache
+bash .pi/scripts/validation-cache.sh init <task-id>
+bash .pi/scripts/validation-cache.sh summary <task-id>
+```

package/templates/pi/prompts/scope-analyzer.md

@@ -0,0 +1,254 @@
+# Scope Analyzer Workflow
+
+**Purpose:** Automatically analyze proposed changes and determine scope classification (simple/moderate/complex/critical) to select appropriate validators.
+
+---
+
+## Prerequisites
+
+- Changes proposed (diff, branch, or description)
+- `.pi/` blueprint exists
+- Scope classification rules defined in INDEX.md
+
+---
+
+## Canonical Reference Requirement
+
+**Analyzer output must reference blueprint scope definitions:**
+
+```markdown
+<!--
+Canonical Reference: .pi/INDEX.md#scope-classification
+Scope determination follows Guardian framework rules
+-->
+```
+
+---
+
+## Workflow Steps
+
+### 1. Gather Change Information
+
+Collect data about proposed changes:
+
+```bash
+# If diff available
+git diff main --stat
+git diff main --numstat
+
+# If branch available
+git log main..HEAD --oneline
+git diff main..HEAD --shortstat
+
+# If files specified
+for file in [files]; do
+  lines=$(wc -l < "$file")
+  echo "$file: $lines lines"
+done
+```
+
+### 2. File Count Analysis
+
+Count files affected:
+
+```bash
+# Files changed
+CHANGED_FILES=$(git diff main --name-only | wc -l)
+
+# Categories
+CONFIG_FILES=$(git diff main --name-only | grep -E '\.(json|yaml|toml|config)' | wc -l)
+SOURCE_FILES=$(git diff main --name-only | grep -E 'src/' | wc -l)
+TEST_FILES=$(git diff main --name-only | grep -E 'test|spec' | wc -l)
+DOC_FILES=$(git diff main --name-only | grep -E '\.(md|rst)' | wc -l)
+```
+
+### 3. Lines Changed Analysis
+
+Calculate lines changed:
+
+```bash
+# Total lines
+ADDED=$(git diff main --numstat | awk '{sum+=$1} END {print sum}')
+REMOVED=$(git diff main --numstat | awk '{sum+=$2} END {print sum}')
+NET=$((ADDED - REMOVED))
+
+# Per-file breakdown
+git diff main --numstat | while read add rem file; do
+  echo "$file: +$add -$rem"
+done
+```
+
+### 4. Complexity Indicators
+
+Check for complexity indicators:
+
+```bash
+# New dependencies
+NEW_DEPS=$(git diff main -- package.json | grep -E '^\+.*"' | grep -v '^\+\+\+' | wc -l)
+
+# New files created
+NEW_FILES=$(git diff main --name-status | grep '^A' | wc -l)
+
+# Deleted files
+DEL_FILES=$(git diff main --name-status | grep '^D' | wc -l)
+
+# Core file changes (high impact)
+CORE_FILES=$(git diff main --name-only | grep -E '(index|main|app|config)' | wc -l)
+
+# API changes
+API_CHANGES=$(git diff main --name-only | grep -E '(api|route|endpoint|handler)' | wc -l)
+
+# Auth/security related
+SECURITY_FILES=$(git diff main --name-only | grep -E '(auth|security|crypto|permission)' | wc -l)
+```
+
+### 5. Scope Classification
+
+Apply classification rules from INDEX.md:
+
+**Classification Matrix:**
+
+| Indicator | Simple | Moderate | Complex | Critical |
+|-----------|--------|----------|---------|----------|
+| Files changed | 1 | 2-5 | 5-15 | 15+ |
+| Lines changed | <50 | 50-200 | 200-500 | 500+ |
+| New dependencies | 0 | 0-2 | 2-5 | 5+ |
+| Core file changes | 0 | 0-1 | 1-2 | 2+ |
+| Security changes | 0 | 0 | 1+ | any |
+| API changes | 0 | 0-1 | 1-3 | 3+ |
+
+**Decision Logic:**
+
+```markdown
+## Scope Calculation
+
+### Primary Metrics
+- Files: [N]
+- Lines: [M]
+
+### Secondary Indicators
+- New deps: [D]
+- Core files: [C]
+- Security: [S]
+- API: [A]
+
+### Classification
+[Apply rules and determine scope]
+
+### Required Validators
+[List validators based on scope]
+```
+
+### 6. Validator Selection
+
+Select validators based on scope:
+
+**Validator Requirements by Scope:**
+
+| Scope | Required Validators |
+|-------|---------------------|
+| Simple | ci (automated) |
+| Moderate | ci + architecture |
+| Complex | ci + architecture + security + test |
+| Critical | All validators + human approval |
+
+**Output validator list:**
+
+```markdown
+## Validators Required
+
+Based on scope [SCOPE]:
+- ✅ validate-ci.sh (always)
+- ✅ validate-architecture.sh (moderate+)
+- ✅ validate-security.sh (complex+)
+- ✅ validate-tests.sh (complex+)
+- ✅ validate-operations.sh (critical)
+- ⚠️ Human approval required (critical only)
+```
+
+### 7. Risk Assessment
+
+Assess risk factors:
+
+```markdown
+## Risk Factors
+
+### High Risk Indicators
+- [ ] Security-related changes
+- [ ] Auth/permission changes
+- [ ] Database schema changes
+- [ ] Breaking API changes
+- [ ] Core architecture changes
+
+### Medium Risk Indicators
+- [ ] New dependencies
+- [ ] Configuration changes
+- [ ] Multiple file changes
+
+### Low Risk
+- [ ] Single file
+- [ ] Documentation only
+- [ ] Test files only
+
+### Risk Level: [HIGH/MEDIUM/LOW]
+```
+
+---
+
+## Output Summary
+
+```markdown
+## Scope Analysis Report
+
+<!--
+Canonical Reference: .pi/INDEX.md#scope-classification
+-->
+
+### Change Summary
+- Files: [N]
+- Lines added: [+X]
+- Lines removed: [-Y]
+- Net change: [Z]
+
+### Scope Classification
+- **Result: [SCOPE]**
+- Files threshold: [N] (threshold: [X])
+- Lines threshold: [M] (threshold: [Y])
+
+### Complexity Factors
+- New dependencies: [D]
+- Core files affected: [C]
+- Security changes: [S]
+- API changes: [A]
+
+### Validators Required
+[List with justification]
+
+### Risk Level: [LEVEL]
+
+### Recommendations
+- [Implementation approach suggestion]
+- [Validation sequence suggestion]
+```
+
+---
+
+## Acceptance Criteria
+
+- [ ] File count accurate
+- [ ] Lines changed calculated
+- [ ] Complexity indicators checked
+- [ ] Scope classification correct per INDEX.md rules
+- [ ] Validators selected appropriately
+- [ ] Risk level assessed
+- [ ] Canonical reference included in output
+
+---
+
+## Next Workflow
+
+After scope determined:
+- Simple: Proceed directly to implementation
+- Moderate: Run `/blueprint-validate`, then implementation
+- Complex: Run `/blueprint-validate` + `/sync-check`, then implementation
+- Critical: Get human approval, then full validation sequence

package/templates/pi/prompts/sync-check.md

@@ -0,0 +1,230 @@
+# Sync Check Workflow
+
+<!--
+Canonical Reference: .pi/prompts/sync-check.md
+Blueprint Source: Guardian Framework v1.2
+-->
+
+**Purpose:** Verify generated exports (.claude/, .opencode/, .agents/) are in sync with .pi/ blueprint source. Includes architecture sync verification.
+
+---
+
+## Prerequisites
+
+- `.pi/` blueprint exists
+- At least one export format generated
+- `guardian.manifest.json` exists
+
+---
+
+## Architecture Sync Verification
+
+**Check architecture CHANGELOG for pending changes:**
+
+```bash
+# Check for pending (not synced) changes in CHANGELOG
+grep -E "Status.*pending" .pi/architecture/CHANGELOG.md | head -10
+
+# Check last architecture sync date
+jq -r '.lastArchitectureSync' guardian.manifest.json
+```
+
+**Pending changes indicate:**
+- Implementation files may have outdated canonical references
+- Architecture spec differs from implementation
+- Need `/blueprint-update` to sync
+
+**Canonical Reference Requirement**
+
+**Generated files must include canonical reference header:**
+
+```typescript
+/**
+ * Canonical Reference: .pi/[source-path].md
+ * Blueprint Source: Guardian Framework v[X]
+ * Generated: [timestamp]
+ * DO NOT EDIT DIRECTLY - Modify source in .pi/
+ */
+```
+
+**Or for markdown:**
+```markdown
+<!--
+Canonical Reference: .pi/[source-path].md
+Blueprint Source: Guardian Framework v[X]
+Generated: [timestamp]
+DO NOT EDIT DIRECTLY - Modify source in .pi/
+-->
+```
+
+---
+
+## Workflow Steps
+
+### 1. Load Manifest
+
+Read the manifest to know what files should exist:
+
+```bash
+cat guardian.manifest.json | jq '.files'
+```
+
+### 2. Check Export Existence
+
+Verify all exported files exist:
+
+```bash
+# Check .claude/ exports
+jq -r '.exports.claude[]' guardian.manifest.json | while read file; do
+  if [ -f "$file" ]; then
+    echo "✅ $file exists"
+  else
+    echo "❌ MISSING: $file"
+  fi
+done
+
+# Check .opencode/ exports (if configured)
+jq -r '.exports.opencode[]' guardian.manifest.json 2>/dev/null | while read file; do
+  if [ -f "$file" ]; then
+    echo "✅ $file exists"
+  else
+    echo "❌ MISSING: $file"
+  fi
+done
+```
+
+### 3. Hash Comparison
+
+Compare file hashes from manifest to actual files:
+
+```bash
+jq -r '.files | to_entries[] | "\(.key) \(.value.hash)"' guardian.manifest.json | while read path hash; do
+  current_hash=$(sha256sum "$path" | cut -d' ' -f1)
+  if [ "$current_hash" = "$hash" ]; then
+    echo "✅ $path: hash matches"
+  else
+    echo "❌ $path: HASH MISMATCH (modified)"
+  fi
+done
+```
+
+### 4. Canonical Header Validation
+
+Check that generated files have proper canonical reference:
+
+```bash
+for file in .claude/**/*.md .opencode/**/*.md; do
+  if [ -f "$file" ]; then
+    if grep -q "Canonical Reference:" "$file"; then
+      # Extract and verify reference
+      ref=$(grep "Canonical Reference:" "$file" | head -1)
+      source=$(echo "$ref" | grep -o '.pi/[^"]*' | head -1)
+      if [ -f "$source" ]; then
+        echo "✅ $file -> $source (valid ref)"
+      else
+        echo "❌ $file references non-existent $source"
+      fi
+    else
+      echo "❌ $file missing canonical reference header"
+    fi
+  fi
+done
+```
+
+### 5. Drift Detection
+
+Detect manual modifications to generated files:
+
+```bash
+# Files modified after generation
+for file in .claude/**/*.md; do
+  gen_time=$(grep "Generated:" "$file" | grep -o '[0-9-]*')
+  mod_time=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file")
+  # Compare timestamps
+  if [ "$mod_time" -gt "$(date -d "$gen_time" +%s 2>/dev/null || echo 0)" ]; then
+    echo "⚠️ $file modified after generation"
+  fi
+done
+```
+
+### 6. Source Freshness Check
+
+Check if blueprint source is newer than exports:
+
+```bash
+for mapping in $(jq -r '.generationMappings[] | "\(.source) \(.destination)"' guardian.manifest.json); do
+  source=$(echo "$mapping" | cut -d' ' -f1)
+  dest=$(echo "$mapping" | cut -d' ' -f2)
+  if [ -f "$source" ] && [ -f "$dest" ]; then
+    source_time=$(stat -c %Y "$source" 2>/dev/null || stat -f %m "$source")
+    dest_time=$(stat -c %Y "$dest" 2>/dev/null || stat -f %m "$dest")
+    if [ "$source_time" -gt "$dest_time" ]; then
+      echo "⚠️ $source newer than $dest (needs regeneration)"
+    fi
+  fi
+done
+```
+
+---
+
+## Output Summary
+
+```markdown
+## Sync Check Report
+
+### Existence Check
+- Total Expected: [N]
+- Found: [M]
+- Missing: [N-M]
+
+### Hash Verification
+- Matching: [X]
+- Modified: [Y]
+
+### Canonical References
+- Valid: [A]
+- Missing: [B]
+- Broken: [C]
+
+### Drift Detection
+- Unmodified: [D]
+- Manual edits: [E]
+
+### Freshness
+- Up-to-date: [F]
+- Needs regeneration: [G]
+
+### Recommendation
+- [PASS: All in sync]
+- [FAIL: Run `guardian generate`]
+```
+
+---
+
+## Error Handling
+
+| Issue | Solution |
+|-------|----------|
+| Missing exports | Run `guardian generate` |
+| Hash mismatch | Regenerate or update source |
+| Missing canonical header | Regenerate with current framework |
+| Manual edits detected | Migrate edits to .pi/ source, regenerate |
+| Source newer than export | Run `guardian generate` |
+
+---
+
+## Acceptance Criteria
+
+- [ ] All expected exports exist
+- [ ] All file hashes match manifest
+- [ ] All generated files have canonical reference headers
+- [ ] No manual edits in generated files (or documented)
+- [ ] Blueprint sources not newer than exports
+- [ ] Sync status: PASS
+
+---
+
+## Next Workflow
+
+- If PASS: Proceed with implementation
+- If FAIL: Run `guardian generate` then recheck