guardian-framework 0.1.0

package/templates/pi/prompts/epic-template.md

@@ -0,0 +1,186 @@
+# Guardian Epic Template
+
+> **Use this template for feature epics and platform-hardening epics derived from canonical architecture modules.**
+> Every epic generated by `/architect` follows this contract. The YAML front matter is parsed by Guardian for pipeline orchestration; the body is the human-readable epic description.
+
+## Purpose
+
+Defines the structure for Guardian epics. Every epic generated by `/architect` follows this contract.
+
+---
+
+## Epic Title
+
+`<type>: <feature or hardening stream>`
+
+Examples:
+- `feature: gate decision resume flow`
+- `hardening: tenant-safe SSE and replay conformance`
+- `platform: architecture and quality CI guardrails`
+
+---
+
+## Why
+
+Describe the business, platform, reliability, security, or operational reason.
+
+Prompts:
+- What outcome does this epic unlock?
+- What risk does it reduce?
+- Why now?
+
+---
+
+## Target Outcome
+
+Define the end state in concrete language.
+
+Example:
+- Gate decisions resume runs deterministically through the outbox → queue → worker path.
+- Replay remains audit-safe and version-compatible.
+- Guardian CI blocks merges that violate architecture conformance.
+
+---
+
+## Scope
+
+State the exact scope boundaries.
+
+Include:
+- primary use case or hardening stream
+- touched bounded contexts
+- touched architecture layers
+- touched runtime or operational behavior
+
+---
+
+## In Scope
+
+- ...
+- ...
+- ...
+
+## Out of Scope
+
+- ...
+- ...
+- ...
+
+---
+
+## Impacted Layers
+
+Mark all that apply.
+
+- [ ] Overview / orchestration
+- [ ] Domain
+- [ ] Application
+- [ ] Infrastructure
+- [ ] Runtime execution
+- [ ] Security
+- [ ] Operations
+
+---
+
+## Architecture Constraints
+
+List non-negotiable rules from canonical docs.
+
+Examples:
+- `Run` aggregate remains the source of truth for lifecycle and gate state.
+- Tenant-scoped DB work must use `begin_tenant_transaction()`.
+- Event ordering remains authoritative in Postgres by `(run_id, sequence)`.
+- Production SSE uses Redis Streams + DB catch-up, not non-durable Pub/Sub.
+
+---
+
+## Dependency Map
+
+List issue order using dependency direction.
+
+1. contract issue
+2. schema/index issue
+3. repository/service issue
+4. handler/runtime issue
+5. verification issue
+6. rollout/runbook issue
+
+---
+
+## Required Child Issues
+
+- [ ] Contract and architecture reconciliation
+- [ ] Schema/index/config changes
+- [ ] Implementation issues by layer
+- [ ] Verification/conformance issue
+- [ ] Rollout/runbook/observability issue
+
+---
+
+## Required Reviewers
+
+- [ ] Architecture
+- [ ] Security
+- [ ] Operations
+- [ ] Backend implementation owner
+
+---
+
+## Verification Strategy
+
+Describe what must prove the epic is complete.
+
+Include as applicable:
+- unit tests
+- integration tests
+- architecture conformance tests
+- migration verification
+- security checks
+- observability validation
+- rollout rehearsal or dry run
+
+---
+
+## Rollout and Risk Notes
+
+Describe:
+- feature flag or staged rollout needed or not
+- migration ordering risks
+- backwards compatibility concerns
+- failure modes
+- rollback plan
+
+---
+
+## Canonical References
+
+Must include exact docs used to derive this epic.
+
+Minimum:
+- `.pi/architecture/modules/<module>.md`
+- relevant ADRs
+- relevant workflow docs
+
+Recommended pattern:
+- `.pi/architecture/modules/<module>.md`
+- `.pi/architecture/decisions/ADR-*.md`
+- `.pi/prompts/epic-plan.md`
+- `.pi/prompts/issue-implementation-series.md`
+- layer-specific references for the impacted work
+
+---
+
+## Epic Checklist
+
+- [ ] Scope is bounded
+- [ ] Impacted layers are identified
+- [ ] Architecture constraints are explicit
+- [ ] Dependency order is explicit
+- [ ] Required tests are explicit
+- [ ] Required CI gates are explicit
+- [ ] Reviewer map is explicit
+- [ ] Rollout notes exist
+
+---
+
+*Use this epic template before generating child issues.*

package/templates/pi/prompts/feature-development.md

@@ -0,0 +1,131 @@
+# Feature Development Workflow
+
+<!--
+Canonical Reference: .pi/prompts/feature-development.md
+Blueprint Source: Guardian Framework v1.2
+-->
+
+**Scope:** Moderate, Complex, Critical
+**Optimized for:** Minimal token usage via shift-left validation + automated post-code checks
+
+## Canonical Reference Requirement
+
+**All implementation files created/modified in this workflow must include:**
+
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/modules/[module].md#[section]
+ * Implements: [feature from design proposal]
+ * Issue: #[issue-number]
+ * Last Architecture Sync: [check CHANGELOG.md]
+```
+
+**Before implementation:**
+1. Check `.pi/architecture/CHANGELOG.md` for pending changes affecting target module
+2. Verify architecture module doc is current
+
+**Validation Phase includes canonical reference check:** `validate-canonical.sh`
+
+## Flow
+
+```
+User Request
+    │
+    ▼
+┌─────────────────────────────────┐
+│ 1. COORDINATOR: Classify scope  │
+│    Load: context/project.md     │
+│    Output: scope + validators   │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 2. ISSUE-CREATOR: Create issue  │
+│    Output: GitHub issue #N      │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────┐
+│ 3. VALIDATORS (Parallel): Plan Review ONLY  │
+│    • architecture-validator (Moderate+)     │
+│    • security-validator (Complex+)          │
+│    Load: context/checklists.md (plan section)│
+│    Output: Validation Contract (signed)     │
+└──────────────┬──────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 4. COORDINATOR: Synthesize plan │
+│    Output: Design Proposal      │
+│    → User approval if Critical  │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────┐
+│ 5. CODE-DEVELOPER: Implement         │
+│    Input: Design Proposal + Contract │
+│    Load: context/patterns.md         │
+│    Add: Canonical Reference Headers  │
+│    Output: Code + tests             │
+└──────────────┬───────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────┐
+│ 6. POST-CODE: Automated Checks (NO LLM)     │
+│    • bash .pi/scripts/validate-ci.sh    │
+│    • bash .pi/scripts/validate-tests.sh │
+│    • bash .pi/scripts/validate-operations.sh   │
+│    • bash .pi/scripts/validate-security.sh   │
+│    • bash .pi/scripts/validate-canonical.sh│
+│    Output: Pass/Fail per check              │
+└──────────────┬──────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────┐
+│ 7. LLM VALIDATORS: Wiring Checks ONLY       │
+│    • architecture-validator: callers, dupes │
+│    • security-validator: manual review if   │
+│      automated scan flagged something       │
+│    Output: Final verdict                    │
+└──────────────┬──────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 8. CI-MR: Create PR + merge     │
+│    Output: Merged PR            │
+└─────────────────────────────────┘
+```
+
+## Key Optimization: Shift-Left Validation
+
+**Old (token-heavy):**
+- Validators review plan → Validators review code (same checks twice)
+- 5 LLM validators × 2 passes = 10 LLM calls
+
+**New (token-optimized):**
+- Validators review plan ONCE → Sign Validation Contract
+- Post-code = automated scripts + wiring checks only
+- 2 LLM validators × 1 pass + 4 automated scripts = 2 LLM calls
+
+## Retry with Caching
+
+If post-code wiring checks fail:
+1. `validation-cache.sh get-failed <task-id> architecture-validator`
+2. Re-check ONLY failed items (not all checks)
+3. `validation-cache.sh record <task-id> <validator> <check> pass`
+4. Repeat until all pass
+
+## Commands
+
+```bash
+# Run all automated validators
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-tests.sh
+bash .pi/scripts/validate-operations.sh [src_dir]
+bash .pi/scripts/validate-security.sh [src_dir]
+bash .pi/scripts/validate-canonical.sh  # Check canonical references
+
+# Validation cache
+bash .pi/scripts/validation-cache.sh init <task-id>
+bash .pi/scripts/validation-cache.sh summary <task-id>
+```

package/templates/pi/prompts/git-issues.md

@@ -0,0 +1,243 @@
+# Git Issues Workflow
+
+**Purpose:** Create epics/milestones and all issues in GitHub or GitLab, including the tracking issue.
+
+---
+
+## Prerequisites
+
+- Issue drafts approved (from `/issue-draft`)
+- Git repository tool configured (`{{REPOTOOL}}`)
+- Repository remote properly configured
+
+---
+
+## Workflow Steps
+
+### 1. Verify Repository Access
+
+Check that the repository tool is configured and authenticated:
+
+```bash
+# For GitHub (gh)
+gh auth status
+gh repo view {{REPOSITORY}}
+
+# For GitLab (glab)
+glab auth status
+glab repo view {{REPOSITORY}}
+```
+
+### 2. Create Epic/Milestone
+
+**For GitHub (using gh):**
+
+```bash
+# Create milestone
+gh api repos/{{REPOSITORY}}/milestones \
+  -f title="[EPIC_NAME]" \
+  -f description="[EPIC_DESCRIPTION]" \
+  -f state="open"
+
+# Get milestone number
+gh api repos/{{REPOSITORY}}/milestones --jq '.[] | select(.title=="[EPIC_NAME]") | .number'
+```
+
+**For GitLab (using glab):**
+
+```bash
+# Create epic (GitLab Premium/Ultimate)
+glab api projects/:id/epics \
+  -f title="[EPIC_NAME]" \
+  -f description="[EPIC_DESCRIPTION]" \
+  -f labels="epic"
+
+# Or create milestone for GitLab Free
+glab api projects/:id/milestones \
+  -f title="[EPIC_NAME]" \
+  -f description="[EPIC_DESCRIPTION]"
+```
+
+### 3. Create Individual Issues
+
+**For GitHub (gh):**
+
+```bash
+gh issue create \
+  --title "[ISSUE_TITLE]" \
+  --body "[ISSUE_BODY_FROM_DRAFT]" \
+  --label "type:[feature/bug/refactor],scope:[simple/moderate/complex]" \
+  --milestone "[MILESTONE_NUMBER]"
+```
+
+**For GitLab (glab):**
+
+```bash
+glab issue create \
+  --title "[ISSUE_TITLE]" \
+  --description "[ISSUE_BODY_FROM_DRAFT]" \
+  --label "type:[feature/bug/refactor],scope:[simple/moderate/complex]" \
+  --milestone "[MILESTONE_ID]"
+```
+
+### 4. Record Issue Numbers
+
+After creating each issue, record the issue number for the tracking issue:
+
+```markdown
+### Issue Numbers Created
+- Issue 1: #[number]
+- Issue 2: #[number]
+- Issue 3: #[number]
+- Milestone/Epic: #[number]
+```
+
+### 5. Create Tracking Issue
+
+Create the tracking issue with links to all created issues:
+
+**GitHub Tracking Issue:**
+
+```bash
+gh issue create \
+  --title "Tracking: [EPIC_NAME]" \
+  --body "$(cat <<'EOF'
+## Epic Progress Tracking
+
+### Milestone: #[milestone_number]
+
+### Issues Checklist
+- [ ] #[issue_1] - [Issue title]
+- [ ] #[issue_2] - [Issue title]
+- [ ] #[issue_3] - [Issue title]
+
+### Progress
+- Total Issues: [N]
+- Completed: 0/[N] (0%)
+- In Progress: 0/[N] (0%)
+
+### Timeline
+- Start: [date]
+- Target: [date]
+
+---
+*This issue will be updated as epic progresses*
+EOF
+)" \
+  --label "tracking,epic"
+```
+
+**GitLab Tracking Issue:**
+
+```bash
+glab issue create \
+  --title "Tracking: [EPIC_NAME]" \
+  --description "$(cat <<'EOF'
+## Epic Progress Tracking
+
+### Epic: #[epic_number]
+
+### Child Issues Checklist
+- [ ] #[issue_1] - [Issue title]
+- [ ] #[issue_2] - [Issue title]
+- [ ] #[issue_3] - [Issue title]
+
+### Progress
+- Total Issues: [N]
+- Completed: 0/[N] (0%)
+
+---
+*This issue will be updated as epic progresses*
+EOF
+)" \
+  --label "tracking,epic"
+```
+
+### 6. Link Issues to Epic/Milestone
+
+**For GitHub:**
+```bash
+# Issues automatically linked to milestone via --milestone flag
+# Verify linking
+gh issue view [issue_number] --json milestone
+```
+
+**For GitLab:**
+```bash
+# Link issues to epic (Premium/Ultimate)
+glab api projects/:id/issues/[issue_iid] \
+  -f epic_id="[epic_id]"
+```
+
+### 7. Verify Creation
+
+Verify all issues and tracking are created correctly:
+
+```bash
+# For GitHub
+gh issue list --milestone "[MILESTONE_TITLE]" --limit 50
+
+# For GitLab
+glab issue list --milestone "[MILESTONE_TITLE]"
+```
+
+---
+
+## Output Summary
+
+After completion, provide:
+
+```markdown
+## Git Issues Created
+
+### Repository: {{REPOSITORY}}
+### Tool: {{REPOTOOL}}
+
+### Epic/Milestone
+- Title: [EPIC_NAME]
+- Number/ID: #[number]
+
+### Issues Created
+| # | Title | Scope | Status |
+|---|-------|-------|--------|
+| #[n] | [title] | [scope] | open |
+| #[n] | [title] | [scope] | open |
+| #[n] | [title] | [scope] | open |
+
+### Tracking Issue
+- Number: #[number]
+- Title: Tracking: [EPIC_NAME]
+
+### Next Steps
+1. Start implementation on first issue
+2. Use `/issue-closeout` when issue complete
+3. Update tracking issue after each merge
+```
+
+---
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| Authentication failed | Run `gh auth login` or `glab auth login` |
+| Repository not found | Check `{{REPOSITORY}}` format (owner/repo) |
+| Milestone creation failed | Use project ID instead of name |
+| Rate limited | Wait and retry, or use API token |
+
+---
+
+## Acceptance Criteria
+
+- [ ] Milestone/Epic created successfully
+- [ ] All individual issues created
+- [ ] Tracking issue created
+- [ ] Issues linked to milestone/epic
+- [ ] Issue numbers recorded
+- [ ] Verification confirms all issues visible
+
+---
+
+## Next Workflow
+
+When ready to close out an issue after implementation, run: `/issue-closeout`

package/templates/pi/prompts/hotfix.md

@@ -0,0 +1,71 @@
+# Emergency Hotfix Workflow
+
+**Scope:** Critical (production issue)
+**Optimized for:** Speed with safety — skip planning, validate post-fix
+
+## Flow
+
+```
+Production Issue Detected
+    │
+    ▼
+┌─────────────────────────────────┐
+│ 1. COORDINATOR: Assess severity │
+│    → If critical: hotfix path   │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 2. CODE-DEVELOPER: Fix ASAP     │
+│    Minimal change, no refactor  │
+│    Load: context/patterns.md    │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 3. ALL AUTOMATED VALIDATORS     │
+│    • validate-ci.sh             │
+│    • validate-tests.sh          │
+│    • validate-operations.sh     │
+│    • validate-security.sh       │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 4. SECURITY-VALIDATOR: Review   │
+│    Hotfixes can introduce vulns │
+│    Manual review REQUIRED       │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 5. CI-MR: Fast-track merge      │
+│    Skip normal review queue     │
+│    Human approval still needed  │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│ 6. POST-MERGE: Full validation  │
+│    Run complete validation suite│
+│    Create follow-up issue if    │
+│    hotfix introduced tech debt  │
+└─────────────────────────────────┘
+```
+
+## Rules
+
+- **NO planning phase** — fix first, validate after
+- **Minimal change** — fix the bug, do NOT refactor
+- **Security review mandatory** — hotfixes are high-risk for introducing vulnerabilities
+- **Post-merge cleanup** — create follow-up issue for any tech debt introduced
+
+## Commands
+
+```bash
+# Full automated validation
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-tests.sh
+bash .pi/scripts/validate-operations.sh [src_dir]
+bash .pi/scripts/validate-security.sh [src_dir]
+```