guardian-framework 0.1.0

package/templates/pi/prompts/blueprint-update.md

@@ -0,0 +1,262 @@
+# Blueprint Update Workflow
+
+**Purpose:** Reverse-sync implementation changes back to blueprint. Use when code evolves and blueprint needs to reflect reality.
+
+---
+
+## Prerequisites
+
+- Implementation changes completed
+- `.pi/` blueprint exists
+- Changes approved and validated
+- Need to update blueprint to match new reality
+
+---
+
+## Canonical Reference Requirement
+
+**When updating blueprint from implementation:**
+
+```markdown
+<!--
+Canonical Reference: .pi/[file].md
+Blueprint Source: Guardian Framework v[X]
+Updated from implementation: [date]
+Implementation source: src/[file].ts
+-->
+```
+
+**Implementation file must reference blueprint:**
+
+```typescript
+/**
+ * Canonical Reference: .pi/[blueprint-section]
+ * Implementation of [spec-name]
+ * Changes should sync back to blueprint via /blueprint-update
+ */
+```
+
+---
+
+## Workflow Steps
+
+### 1. Identify Changes to Sync
+
+Find implementation changes that affect blueprint:
+
+```bash
+# Recent changes
+git log --oneline --since="1 week ago" src/
+
+# Changed files
+git diff HEAD~5 HEAD --name-only src/
+
+# Compare to blueprint
+for file in src/lib/*.ts; do
+  # Check if blueprint mentions this file
+  if ! grep -q "$file" .pi/context/project.md; then
+    echo "⚠️ $file not documented in blueprint"
+  fi
+done
+```
+
+### 2. Categorize Changes
+
+Determine what needs updating:
+
+**Categories:**
+
+| Category | Blueprint File | What to Update |
+|----------|----------------|----------------|
+| Commands | project.md | Build/test/lint commands |
+| Dependencies | project.md | Dependency list |
+| Patterns | patterns.md | New patterns, pattern changes |
+| Architecture | project.md | Structure, modules |
+| Quality gates | AGENTS.md | Validation steps |
+| Workflows | prompts/*.md | Workflow adjustments |
+
+### 3. Extract Updates from Code
+
+For each category, extract current state:
+
+**Commands:**
+```bash
+# Actual commands from package.json
+jq '.scripts.build' package.json
+jq '.scripts.test' package.json
+jq '.scripts.lint' package.json
+```
+
+**Dependencies:**
+```bash
+jq '.dependencies' package.json
+jq '.devDependencies' package.json
+```
+
+**Patterns:**
+```bash
+# Use /pattern-extract workflow for new patterns
+```
+
+### 4. Validate Changes Before Sync
+
+Ensure changes are valid and tested:
+
+```bash
+# Run validators
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-tests.sh
+
+# Check tests pass
+[test command]
+
+# Ensure no breaking changes
+```
+
+### 5. Update Blueprint Files
+
+Apply updates to .pi/ files:
+
+**Update project.md:**
+```markdown
+## Commands (Updated [date])
+
+### Build
+```bash
+[new build command]
+```
+
+## Dependencies (Updated [date])
+- Added: [deps]
+- Removed: [deps]
+```
+
+**Update patterns.md:**
+```markdown
+## Patterns (Updated [date])
+
+### New Patterns
+[From /pattern-extract]
+
+### Updated Patterns
+[Pattern modifications]
+```
+
+**Update AGENTS.md:**
+```markdown
+## Quality Gates (Updated [date])
+- [ ] [new command] succeeds
+```
+
+### 6. Add Sync Metadata
+
+Record update in manifest:
+
+```bash
+# Update guardian.manifest.json
+jq '.lastBlueprintSync = "2026-04-26"' guardian.manifest.json > tmp.json
+mv tmp.json guardian.manifest.json
+
+jq '.blueprintUpdates += [{"date": "2026-04-26", "source": "implementation", "files": ["project.md", "patterns.md"]}]' guardian.manifest.json > tmp.json
+mv tmp.json guardian.manifest.json
+```
+
+### 7. Validate Canonical References
+
+Check implementation files reference blueprint:
+
+```bash
+for file in src/**/*.ts; do
+  if grep -q "Canonical Reference:" "$file"; then
+    ref=$(grep "Canonical Reference:" "$file" | grep -o '.pi/[^"]*')
+    if [ -f "$ref" ]; then
+      echo "✅ $file → $ref"
+    else
+      echo "❌ Invalid ref in $file: $ref"
+      # Add canonical reference
+      echo "Consider adding: Canonical Reference: .pi/context/patterns.md#[section]"
+    fi
+  else
+    echo "⚠️ $file missing canonical reference"
+  fi
+done
+```
+
+---
+
+## Output Summary
+
+```markdown
+## Blueprint Update Report
+
+### Changes Synced
+
+#### project.md
+- Commands updated: [list]
+- Dependencies updated: [list]
+- Architecture updated: [sections]
+
+#### patterns.md
+- Patterns added: [count]
+- Patterns updated: [count]
+
+#### AGENTS.md
+- Quality gates updated: [list]
+
+### Files Modified
+- .pi/context/project.md
+- .pi/context/patterns.md
+- .pi/agent/AGENTS.md
+
+### Canonical Reference Coverage
+- Before: [X]%
+- After: [Y]%
+
+### Manifest Updated
+- lastBlueprintSync: [date]
+- blueprintUpdates: [entry added]
+
+### Next Steps
+1. Review changes in .pi/
+2. Run `/blueprint-validate`
+3. Run `guardian generate`
+```
+
+---
+
+## Acceptance Criteria
+
+- [ ] Implementation changes identified
+- [ ] Changes categorized by type
+- [ ] Changes validated (tests pass)
+- [ ] Blueprint files updated
+- [ ] Sync metadata recorded in manifest
+- [ ] Canonical references in implementation verified
+- [ ] Blueprint integrity maintained
+
+---
+
+## Next Workflow
+
+After blueprint update:
+1. `/blueprint-validate`
+2. `guardian generate`
+3. `/sync-check`
+
+---
+
+## Important Notes
+
+**Reverse sync is exception, not norm:**
+- Blueprint is canonical truth
+- Implementation should follow blueprint
+- Only reverse sync when:
+  - Implementation discovered better approach
+  - Commands evolved organically
+  - New patterns emerged naturally
+  - Bug fixes revealed needed patterns
+
+**Never reverse sync:**
+- Breaking changes without approval
+- Unvalidated code
+- Work-in-progress implementations

package/templates/pi/prompts/blueprint-validate.md

@@ -0,0 +1,218 @@
+# Blueprint Validate Workflow
+
+<!--
+Canonical Reference: .pi/prompts/blueprint-validate.md
+Blueprint Source: Guardian Framework v1.2
+-->
+
+**Purpose:** Validate the `.pi/` blueprint is complete, consistent, and properly structured before starting implementation. Includes architecture documentation validation.
+
+---
+
+## Prerequisites
+
+- `.pi/` directory exists with blueprint files
+- No active implementation work in progress
+
+---
+
+## Architecture Documentation Validation
+
+**Check architecture structure exists:**
+
+```bash
+# Required architecture directories
+for dir in architecture/modules architecture/diagrams architecture/decisions; do
+  if [ -d ".pi/$dir" ]; then
+    echo "✅ .pi/$dir exists"
+  else
+    echo "❌ MISSING: .pi/$dir"
+  fi
+done
+
+# Required files
+if [ -f ".pi/architecture/CHANGELOG.md" ]; then
+  echo "✅ Architecture CHANGELOG exists"
+else
+  echo "❌ MISSING: .pi/architecture/CHANGELOG.md (required for change tracking)"
+fi
+```
+
+**Architecture Module Validation:**
+
+Each module in `.pi/architecture/modules/` must have:
+- [ ] Overview section
+- [ ] Components table with file paths
+- [ ] Data flow documentation
+- [ ] Dependencies section
+- [ ] Security considerations
+- [ ] Testing requirements
+- [ ] Change log references
+
+---
+
+## Workflow Steps
+
+### 1. Structure Validation
+
+Check that all required blueprint directories exist:
+
+```bash
+# Required directories
+for dir in agent context skills prompts scripts; do
+  if [ -d ".pi/$dir" ]; then
+    echo "✅ .pi/$dir exists"
+  else
+    echo "❌ MISSING: .pi/$dir"
+  fi
+done
+```
+
+**Required Structure:**
+
+```
+.pi/
+├── agent/AGENTS.md          # Required
+├── context/
+│   ├── project.md           # Required
+│   ├── patterns.md          # Required
+│   ├── checklists.md        # Optional
+│   └── output-formats.md    # Optional
+├── skills/agents/           # Required
+├── skills/validators/       # Required
+├── prompts/                 # Required
+└── scripts/                 # Required
+```
+
+### 2. AGENTS.md Validation
+
+Verify project instructions are complete:
+
+**Checklist:**
+- [ ] Project name and version defined
+- [ ] Development commands listed
+- [ ] Architecture patterns documented
+- [ ] Key files to read specified
+- [ ] Quality gates defined
+
+### 3. Context Files Validation
+
+Validate each context file:
+
+**project.md:**
+- [ ] Project facts accurate
+- [ ] Build/test/lint commands match reality
+- [ ] Dependencies listed
+
+**patterns.md:**
+- [ ] Code patterns for language exist
+- [ ] Patterns are current (not stale)
+- [ ] Example code snippets valid
+
+### 4. Cross-Reference Validation
+
+Check that blueprint references are consistent:
+
+```bash
+# Check for broken references in blueprint
+grep -r "see .pi/" .pi/ | while read line; do
+  ref=$(echo "$line" | grep -o '.pi/[^"]*')
+  if [ ! -e "$ref" ]; then
+    echo "❌ BROKEN REF: $ref"
+  fi
+done
+```
+
+### 5. Workflow Integrity Check
+
+Verify all workflows have required sections:
+
+```bash
+for workflow in .pi/prompts/*.md; do
+  echo "Checking: $workflow"
+  # Check for required sections
+  grep -q "## Prerequisites" "$workflow" || echo "  ⚠️ Missing Prerequisites"
+  grep -q "## Workflow Steps" "$workflow" || echo "  ⚠️ Missing Workflow Steps"
+  grep -q "## Acceptance Criteria" "$workflow" || echo "  ⚠️ Missing Acceptance Criteria"
+done
+```
+
+### 6. Validator Scripts Check
+
+Ensure validator scripts are executable and functional:
+
+```bash
+for script in .pi/scripts/validate-*.sh; do
+  if [ -x "$script" ]; then
+    echo "✅ $script is executable"
+  else
+    echo "❌ $script not executable"
+  fi
+  # Dry-run check
+  bash "$script" --dry-run 2>/dev/null || echo "⚠️ $script may have issues"
+done
+```
+
+---
+
+## Canonical Reference Requirement
+
+**All blueprint files must include canonical reference header:**
+
+```markdown
+<!--
+Canonical Reference: .pi/[category]/[filename].md
+Blueprint Source: Guardian Framework v[X]
+Generated: NEVER (this is the source)
+-->
+```
+
+**Validation Check:**
+- Each blueprint file must have canonical reference header
+- Reference must point to self (blueprint is source, not generated)
+- Framework version must match manifest
+
+---
+
+## Output Summary
+
+```markdown
+## Blueprint Validation Report
+
+### Structure
+- [PASS/FAIL] Directory structure complete
+
+### Content
+- [PASS/FAIL] AGENTS.md valid
+- [PASS/FAIL] Context files valid
+- [PASS/FAIL] Workflows valid
+
+### References
+- [PASS/FAIL] Cross-references valid
+- [PASS/FAIL] Canonical headers present
+
+### Validators
+- [PASS/FAIL] Scripts executable
+
+### Recommendations
+- [List of fixes needed]
+```
+
+---
+
+## Acceptance Criteria
+
+- [ ] All required directories exist
+- [ ] AGENTS.md has all required sections
+- [ ] Context files are valid and current
+- [ ] No broken cross-references
+- [ ] All workflows have required structure
+- [ ] Validator scripts are executable
+- [ ] All files have canonical reference headers
+- [ ] Blueprint ready for implementation
+
+---
+
+## Next Workflow
+
+When blueprint validated, proceed to `/epic-plan` or `/feature-development`

package/templates/pi/prompts/bug-fix.md

@@ -0,0 +1,50 @@
+# Bug Fix Workflow
+
+**Scope:** Simple, Moderate
+**Optimized for:** Speed — minimal validation, direct fix
+
+## Flow
+
+```
+Bug Report
+    │
+    ▼
+┌─────────────────────────────────┐
+│ 1. COORDINATOR: Classify scope  │
+│    Most bugs = Simple/Moderate  │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 2. CODE-DEVELOPER: Fix bug      │
+│    Load: context/patterns.md    │
+│    Output: Fixed code + test    │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 3. AUTOMATED: Run validators    │
+│    • validate-ci.sh             │
+│    • validate-tests.sh          │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 4. CI-MR: Create PR + merge     │
+│    Simple scope = ci-mr only    │
+└─────────────────────────────────┘
+```
+
+## Rules
+
+- **Simple bugs** (1 file, < 50 lines): Fix → automated checks → merge. No LLM validators.
+- **Moderate bugs** (2-5 files): Fix → automated checks → architecture-validator wiring check → merge.
+- **Complex bugs** (root cause in architecture): Escalate to Feature Development workflow.
+
+## Commands
+
+```bash
+# Quick fix verification
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-tests.sh
+```

package/templates/pi/prompts/ci-blueprint.md

@@ -0,0 +1,131 @@
+# Guardian CI Blueprint
+
+> **Generates `.gitlab-ci.yml` or `.github/workflows/ci.yml` from architecture conformance requirements.**
+
+## Purpose
+
+Defines the CI/CD pipeline configuration that Guardian generates or validates. Every MR must pass this pipeline before merge.
+
+## Pipeline Structure
+
+```yaml
+stages:
+  - docs_policy
+  - architecture_conformance
+  - lint
+  - static_analysis
+  - unit
+  - integration
+  - security
+  - migration_verify
+  - package_build
+  - release_readiness
+```
+
+## Stage 1: Docs Policy
+
+Verifies MR traceability and documentation sync.
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `mr_traceability_check` | `.pi/scripts/ci/stage_docs_policy.sh` | No |
+| `docs_sync_guard` | `.pi/scripts/ci/stage_docs_policy.sh` | No |
+
+## Stage 2: Architecture Conformance
+
+11+ architectural contract checks.
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `tenant_isolation_conformance` | `.pi/scripts/ci/check_architecture_conformance.sh` | No |
+| `event_ordering_conformance` | `.pi/scripts/ci/check_architecture_conformance.sh` | No |
+| `outbox_dlq_conformance` | `.pi/scripts/ci/check_architecture_conformance.sh` | No |
+| `replay_upcaster_conformance` | `.pi/scripts/ci/check_architecture_conformance.sh` | No |
+| `architecture_sanity` | `.pi/scripts/ci/check_architecture_conformance.sh` | No |
+| `import_boundary_check` | `.pi/scripts/ci/check_architecture_conformance.sh` | No |
+
+## Stage 3: Lint
+
+Language-specific linting.
+
+| Language | Lint Job | Format Job |
+|----------|----------|------------|
+| Python | `ruff check .` | `ruff format --check .` |
+| TypeScript | `biome check .` | `biome format --check .` |
+| Rust | `cargo clippy -- -D warnings` | `cargo fmt --check` |
+| Go | `golangci-lint run` | `gofmt -d .` |
+
+## Stage 4: Static Analysis
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `type_check` | `mypy` / `tsc --noEmit` / `cargo check` / `go vet` | No |
+| `import_boundary_check` | `.pi/scripts/ci/stage_static_analysis.sh` | No |
+| `sanity_checks` | `.pi/scripts/ci/stage_static_analysis.sh` | No |
+| `settings_env_collision_check` | `.pi/scripts/ci/stage_static_analysis.sh` | No |
+
+## Stage 5: Unit
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `unit_domain` | `pytest tests/unit/domain` | No |
+| `unit_application` | `pytest tests/unit/application` | No |
+| `unit_contract` | `pytest tests/contract` | No |
+| `unit_verification` | `pytest tests/verification` | No |
+| `coverage_threshold_check` | `.pi/scripts/ci/check_coverage_thresholds.py` | No |
+
+## Stage 6: Integration
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `integration` | `pytest tests/integration` | No |
+
+## Stage 7: Security
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `sbom_and_provenance` | `.pi/scripts/ci/generate_sbom.py` | No |
+| `container_scan` | `trivy image --severity HIGH,CRITICAL` | No |
+| `secret_scan` | `.pi/scripts/ci/secret_scan.py` | No |
+| `dependency_scan` | `pip-audit` / `npm audit` / `cargo audit` | No |
+
+## Stage 8: Migration Verify
+
+**Conditional:** Only triggers when migration-related files change.
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `migration_apply_check` | `alembic upgrade head` | No |
+| `index_policy_verify` | `.pi/scripts/ci/verify_indexes_and_policies.py` | No |
+
+## Stage 9: Package Build
+
+**Conditional:** Only on main branch.
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `build_backend_image` | `docker build -t app:${CI_COMMIT_SHA} .` | Yes |
+
+## Stage 10: Release Readiness
+
+| Job | Script | Allow Failure |
+|-----|--------|---------------|
+| `runbook_readiness_check` | `.pi/scripts/validate-architecture-readiness.sh` | No |
+| `observability_readiness_check` | `.pi/scripts/validate-architecture-readiness.sh` | No |
+| `release_policy_check` | `.pi/scripts/ci/check_release_policy.py` | No |
+
+## Conditional Rules
+
+| Rule | Jobs Using It |
+|------|---------------|
+| `rules_default` (MRs or main branch) | Most jobs |
+| `rules_sonar` (requires `$SONAR_TOKEN` + `$SONAR_HOST_URL`) | coverage_report, sonar_quality_gate |
+| `rules_main_only` | `package_build` |
+| `rules_migration_changes` (migration file changes only) | `migration_verify` stage |
+
+## Generated Pipeline Files
+
+Guardian generates or validates:
+- `.gitlab-ci.yml` for GitLab projects
+- `.github/workflows/ci.yml` for GitHub projects
+- Both are derived from `.pi/scripts/ci/run_hardening_stages.sh`